motherduck-rest-api

REST API の管理

信頼できる情報源

• 現行の MotherDuck REST API ドキュメント、公開 OpenAPI 仕様（https://api.motherduck.com/docs/specs）、またはユーザーから明示的に提供された OpenAPI 仕様を優先してください。
• トークンのスコープと埋め込みの動作については、REST API ドキュメントと Embedded Dives ドキュメントを照合してください。これらには、生のスキーマからは分かりにくい運用上の制約が記載されています。
• MotherDuck MCP の ask_docs_question 機能を利用できる場合は、公開 REST API のガイダンスに変更がないか確認してください。
• エンドポイントの提供状況、プレビューのステータス、トークンのフィールド、ロール要件は、提供された仕様または現行ドキュメントで裏付けられている場合に限り、現行の情報として扱ってください。

基本方針

• REST API はコントロールプレーンとして扱ってください。SQL とデータプレーンのクエリは REST API ではなく、データベース接続を通じて実行してください。
• ユーザーが別の環境を指定しない限り、ベース URL には https://api.motherduck.com を使用してください。
• Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN} で認証し、管理者用の読み書きトークンはバックエンドで管理するシークレットに保管してください。
• REST API の管理に読み取りスケーリング用トークンを使用しないでください。
• 設定変更では、変更前に現在のアカウント、サービスアカウント、Duckling の設定、または Dive のメタデータを把握できるよう、読み取りを先に行うフローを優先してください。
• 現行ドキュメントで API の対象範囲が明示的に拡張されていない限り、POST /v1/users はサービスアカウントの作成として扱ってください。GET /v1/users は組織内のすべてのユーザーとサービスアカウントを一覧表示します。is_service_account と is_deprovisioned で絞り込み、limit／offset でページ分割してください。アクセスレビューや、重複作成を避けるために既存のサービスアカウントを探す際に使用してください。
• サービスアカウントとアクセストークンには、検索可能な任意の説明を設定できます。ワークロードと所有者が分かる説明を設定し、フィールド名は現行の API 仕様で確認してください。
• 環境、パートナー向け、または顧客ごとのセットアップなど、繰り返し可能なプロビジョニングには、スクリプトによる REST 呼び出しより Terraform プロバイダー motherduckdb/motherduck を優先してください。認証には MOTHERDUCK_TOKEN を使用し、サービスアカウント、トークン、Duckling の設定には MOTHERDUCK_ADMIN_TOKEN も使用します。
• 現行ドキュメントに別の記載がない限り、アクティブアカウント、Duckling の設定、サービスアカウントの作成、サービスアカウント用トークンの作成、Dive の埋め込みセッションの各エンドポイントには、組織管理者のベアラートークンが必要だと想定してください。
• 生成されたアクセストークンをログ、ブラウザーコード、クライアントバンドル、コミット済みファイルに公開しないでください。
• 破壊的な削除はユーザーに確認してください。ユーザーを削除すると、そのユーザーとすべてのデータが完全に削除されます。
• エージェント／アカウントのサインアップ（motherduck new または一般公開のサインアップフロー）は、組織の Admin REST API とは別のものとして扱ってください。管理者トークンが利用できないことを理由にアカウントを作成しないでください。
• Dive の埋め込みセッションでは、initial_state を JSON でシリアライズ可能な形式にし、ドキュメントに記載されたサイズ制限内に収めてください。ホストアプリケーションで iframe の状態、ナビゲーション、エクスポートの各メッセージを検証してください。

ワークフロー

1. タスクがサービスアカウントのプロビジョニング、トークン管理、Duckling のサイズ設定、アクティブアカウントの確認、Dive の埋め込みのいずれに該当するかを特定します。
2. 既存の環境から管理者トークンを取得し、対象の username または dive_id を特定します。必須の値を検出できない場合に限り確認を求め、本番環境の識別子を決して捏造しないでください。
3. トークンエンドポイントを呼び出す前にトークンのスコープを確認します。ユーザーは自身のトークンを作成でき、管理者はサービスアカウントのトークンを作成できますが、API を通じて他の非サービスアカウントメンバーのトークンを作成することはできません。
4. Duckling の設定を変更する場合は、まず現在の設定を読み取ります。その後、PUT ペイロードで両方が必要なため、read_write と read_scaling の両方を更新します。
5. 一度しか返されないレスポンスフィールド、特に新しく作成されたトークン文字列と埋め込みセッション文字列を保持します。
6. API エラーはステータスとレスポンス本文を提示します。成功したように見せかけるフォールバックで 400、401、403、404、500 のレスポンスを隠さないでください。
7. 接続済みの MotherDuck MCP サーバーにユーザー管理ツール（create_service_account など）がある場合は、それらを生の HTTP より優先し、一覧に get_user_admin_guide がある場合は、まずこれを呼び出してください。多くの MCP セットアップではこれらのツールが公開されないため、その場合は REST API を直接使用します。references/REST_API_GUIDE.md の MCP 列にツール名との対応が記載されています。

回答、レビュー、または計画の依頼では、コントロールプレーンを変更せずに確認して報告します。作成または更新の依頼では、依頼された範囲内の操作を実行してレスポンスを検証します。破壊的な削除や、より広範な管理上の変更については、確認を得てください。

参考資料

現在のタスクに必要な参考資料のセクションのみを読みます。

• エンドポイントの概要、MCP ツールとの対応、curl の例、検証上限、運用上の注意点については、references/REST_API_GUIDE.md を読んでください。

関連スキル

不足している機能を補う場合に限り、関連スキルを読み込みます。確立済みのコンテキストを再利用してください。

• SQL およびデータプレーンのクエリ作業には motherduck-query
• 接続トークンおよびアプリケーションの接続ポスチャには motherduck-connect
• 管理者トークンの取り扱い、サービスアカウントのポスチャ、アクセス境界に関する質問には motherduck-security-governance
• 埋め込みセッションを発行する前の Dive の設計には motherduck-create-dive