チーム、共有、接続の API ガイド

DUST プラットフォーム内のすべては、チームによって所有され、アクセスされます。このガイドでは、誰が何を閲覧できるかを制御する次の 4 つのレイヤーについて説明します。

コンテキスト — リクエストがどの組織およびチームとして実行されるか。
共有 — 別のチームに、スレッドおよびフォルダーへの閲覧者または編集者アクセスを付与します。
接続 — 共有と出荷を可能にする、2 つのチーム間（通常は異なる組織間）の継続的な合意です。
出荷と分割 — これらの境界を越えて記録を移動または派生させます。

完全なスキーマについては、API リファレンスを参照してください。

リクエストコンテキスト

アイデンティティは AuthD で管理され、プラットフォーム API は次のヘッダーを使用して各呼び出しの範囲を設定します。

Authorization: Bearer <authd-token>
Dust-Ctx-Org-Id: <organization-uuid>
Dust-Ctx-Team-Id: <team-uuid>

Dust-Ctx-Org-Id は組織範囲の呼び出しに必要です。Dust-Ctx-Team-Id は実行主体となるチームを選択し、デフォルトでは組織のルートチームになります（Dust-Ctx-Grp-Id は従来の表記として受け付けられます）。認証および規約を参照してください。

GET /api/v1/me — 現在のユーザー、セッション、アクティブな組織、利用可能な組織
GET /api/v1/me/feature-flags — 呼び出し元の機能フラグ

チーム

チームは組織を分割します。スレッド、フォルダー、共有はすべてチームに属します。チームのメタデータを更新しても、その組織とチーム ID は維持されます。宣言されていない更新プロパティは拒否されます。

操作	メソッドとパス
閲覧可能なチームを一覧表示	`GET /api/v1/teams`
接続済みのパートナーチームを一覧表示	`GET /api/v1/teams/connected`
チームを作成（組織管理者）	`POST /api/v1/org/teams`
組織内のすべてのチームを一覧表示（組織管理者）	`GET /api/v1/org/teams`
チームを更新または削除（組織管理者）	`PATCH` / `DELETE /api/v1/org/teams/{team_id}`
メンバーシップを追加または更新（組織管理者）	`POST /api/v1/org/teams/members`
メンバーシップを一覧表示または削除（組織管理者）	`GET` / `DELETE /api/v1/org/teams/members`

GET /api/v1/teams は q、role、rootId、includeLinked（選択リストに接続済みのパートナーチームを含めるため）をサポートします。GET /api/v1/teams/connected は、アクティブな接続を通じて到達可能なパートナーチーム、つまり共有と出荷の有効な対象を一覧表示します。

共有では、1 つのチームに対し、1 つのオブジェクト（スレッドまたはフォルダー／カテゴリー）へのアクセスを viewer または editor として付与します。付与は関係タプルとして保存されます。また、アクセスは間接的に付与される場合もあります（共有フォルダーはその内容へのアクセスも付与します）。そのため、読み取りモデルには、生の付与一覧と、アクセス権の実効サマリーの 2 つがあります。

curl
TypeScript

curl -fsS "$APID_URL/api/v1/sharing" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item": "thread", "id": "'"$THREAD_ID"'", "teamId": "'"$PARTNER_TEAM_ID"'", "relation": "viewer" }
    ]
  }'

await client.sharing.add({
  items: [
    { item: "thread", id: threadId, teamId: partnerTeamId, relation: "viewer" },
  ],
});

操作	メソッドとパス
共有を作成	`POST /api/v1/sharing`
共有を一覧表示	`GET /api/v1/sharing?direction=in\|out`
共有の関係を更新	`PATCH /api/v1/sharing/{tuple_id}`
共有を削除	`DELETE /api/v1/sharing`（本文：`{ "ids": […] }`）
1 つのオブジェクトに対する実効アクセス	`GET /api/v1/sharing/access-summary?objectId=…&objectType=thread\|bundle`
1 つのパートナーと共有されているすべてのもの	`GET /api/v1/sharing/partner-inventory?teamId=…`

direction=out はチームが共有したものを一覧表示し、direction=in はチームに共有されたものを一覧表示します。アクセスサマリーは、直接付与、フォルダーからの継承、チーム関係を解決し、オブジェクトに対する実効権限を示します。パートナーインベントリーは接続単位のビューであり、接続を一時停止または変更する前に役立ちます。

スレッド側の便利なエンドポイントとして、GET /api/v1/threads/{thread_id}/shared（このスレッドの共有先）と POST /api/v1/threads/permissions（呼び出し元が実行できる操作）があります。詳しくはスレッドガイドを参照してください。

接続

接続（API 名：team link）は 2 つのチームを接続し、チーム間のすべてのアクティビティを制御します。接続には、許可されたデータフローの方向（send、receive、send_receive）が、リクエスト元チームの視点で設定されます。接続は 3 段階のハンドシェイクによって確立されます。リクエスト元がリンクを作成し、パートナーが承認し、リクエスト元が確認します。リンクは招待 code によって指定されます。

操作	メソッドとパス
作成（招待）	`POST /api/v1/connections` — 本文 `{ "allow": "send" \| "receive" \| "send_receive", "email"? }`
接続を一覧表示	`GET /api/v1/connections`
1 件を取得または削除	`GET` / `DELETE /api/v1/connections/{code}`
承認（パートナー）	`PATCH /api/v1/connections/accept`
拒否（パートナー）	`PATCH /api/v1/connections/reject`
確認（リクエスト元）	`PATCH /api/v1/connections/confirm`
キャンセル	`PATCH /api/v1/connections/cancel`
一時停止または再開	`PATCH /api/v1/connections/pause` / `resume`

接続を一時停止すると、関係を削除することなく、その接続に依存する共有および出荷アクティビティが停止します。

方向の変更

アクティブな接続の方向変更もハンドシェイクで行われるため、どちらの側も一方的にデータフローを拡大できません。いずれかのチームが提案し、もう一方のチームが承認し、提案した側が確認します。確認が完了するまでは、以前の方向が引き続き有効です。

POST /api/v1/connections/amend/propose — 本文 { "code", "allow" }
PATCH /api/v1/connections/amend/accept / confirm / cancel

新しい方向ではフローが許可されなくなる共有は、削除されず休止状態になります。

出荷

出荷（API 名前空間：/api/v1/transfers、従来の命名）は、接続済みのチームにスレッドの所有権を移管します。下書きの明細書を作成して送信し、受信側が応答します。ライフサイクル順のエンドポイントは次のとおりです。

段階	メソッドとパス
下書きを作成	`POST /api/v1/transfers`
明細書アイテムを追加、更新、削除	`POST /api/v1/transfers/{transfer_id}/items`, `PATCH` / `DELETE …/items/{item_id}`
プライマリースレッドを設定	`PUT /api/v1/transfers/{transfer_id}/primary-thread`
送信	`POST /api/v1/transfers/{transfer_id}/send`
プレビュー（受信側、送信後）	`GET /api/v1/transfers/{transfer_id}/preview`
応答：承認、拒否、変更依頼	`POST /api/v1/transfers/{transfer_id}/respond`
会話	`POST /api/v1/transfers/{transfer_id}/messages`
キャンセル（下書き、送信済み、または変更依頼済み）	`POST /api/v1/transfers/{transfer_id}/cancel`
失敗した出荷を再試行	`POST /api/v1/transfers/{transfer_id}/retry`
失敗した出荷を放棄	`POST /api/v1/transfers/{transfer_id}/abandon`
停止した出荷の明細書から再開	`POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest`
一覧表示（メールボックスビュー）	`GET /api/v1/transfers?box=inbox\|outbox\|sent`
明細書を含む 1 件を取得	`GET /api/v1/transfers/{transfer_id}`

応答には { "value": "accept" | "reject" | "request_changes" } を指定します（変更依頼には reason が必要です）。一覧表示では、box、view、status、direction=inbound|outbound フィルターをサポートします。

分割

分割は、自チーム内の既存のスレッドから、選択したフィールド、ファイル、識別子のサブセットを含む新しいスレッドを派生させます。通常は、共有または出荷する内容だけを正確に準備し、残りを非公開に保つために使用します。

POST /api/v1/slices — 1 つのスレッドを分割（bundleId で対象フォルダーを選択し、fields などを指定）
POST /api/v1/slices/batch — 1 回の操作で複数のスレッドを派生
GET /api/v1/slices/{slice_id} — Fabric リンクを含む分割

コアモデル — チーム、共有、接続がドメイン内でどのように連携するか
出荷 — 出荷ライフサイクルのセマンティクス
Fabric — 組織間の来歴と開示
API リファレンス — 上記すべてのエンドポイントの完全なスキーマ

ドキュメントの問題を報告

チーム、共有、接続の API ガイド

リクエストコンテキスト

チーム

共有

接続

方向の変更

出荷

分割

関連ページ