リクエスト規約：コンテキストヘッダー、エラー、ローカライズ

組織を範囲とするすべての /api/v1/* エンドポイントは、同じリクエスト規約を共有します。ベアラートークン、操作対象の組織とチームを選択する 2 つのコンテキストヘッダー、JSON ボディ（ファイルのアップロードには代わりに multipart または tus を使用）、統一されたエラー形式、および一覧エンドポイントでのカーソルページネーションです。このページではその規約を説明します。各ドメインのページでは、この規約を前提としています。

コンテキストヘッダー

DUST API のほぼすべてのデータは組織に属し、その組織内のチームに属します。リクエストが操作対象とする組織とチームは、次の 2 つのヘッダーで選択します。

ヘッダー	必須	値
`Dust-Ctx-Org-Id`	組織を範囲とするエンドポイントでは必須	組織の UUID。
`Dust-Ctx-Team-Id`	いいえ	チームの UUID。省略した場合は、組織のルートチームがデフォルトになります。

curl -fsS "https://apid.dustid.io/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID"

実際の利用で重要となる詳細は次のとおりです。

ヘッダー値は UUID である必要があります。不正な形式の値は、エンドポイントが実行される前に 400 INVALID_REQUEST で拒否されます。
X- プレフィックス付きの形式（X-Dust-Ctx-Org-Id、X-Dust-Ctx-Team-Id、および従来のヘッダーペア）もエイリアスとして使用できます。
コンテキストを必要とするエンドポイントでコンテキストが指定されていない場合、エラーコード ORG_ID_REQUIRED または TEAM_ID_REQUIRED が返されます。
一部のエンドポイントはユーザーを範囲とし、コンテキストを必要としません。代表的なものは GET /api/v1/me です。

コンテキストは認可の境界です

認可は、ヘッダーで指定されたチームで操作するユーザーに対して評価されます。同じ呼び出しでも Dust-Ctx-Team-Id が異なれば、返される結果が異なる場合があります。一覧表示、読み取り、書き込みが可能な対象は、そのチームが参照できるもの、つまりチーム自身の記録と、そのチームに共有された記録です。所属していないコンテキストを送信しても権限は昇格しません。リクエストは、実際の所属状況に照らして確認されます。ファイル、フォルダー、関係、スレッドリンク、アセンブリーインポート、証明書フォーム、Fabric、分割、接続済みチームの一覧、公開ページ、公開ページデザイン、アクティビティ、ユーザーディレクトリの各操作では、人とサービスアカウントのどちらについても、選択したチームに現在所属していること、およびそのチームが選択した組織に属していることが必要です。スレッド履歴では、さらにそのスレッドを表示する権限が必要です。スレッド ID を選択してもアクセス権は付与されません。スレッドの作成（一括作成を含む）とテンプレートの作成にも、選択したチームへの現在の所属が必要です。組織管理者向けの所属メンバー一覧は、選択した組織の範囲内に限定されます。チームと共有を参照してください。

ローカライズ

任意の Dust-Ctx-Locale ヘッダーで、サーバーが生成するユーザー向けテキストの言語を選択できます。最も目にする機会が多いのは、エラーの message 文字列です。

Dust-Ctx-Locale: zh-CN

サポートされるロケールは de, es, fr, it, ja, pt, en（デフォルト）と zh-CN です。このヘッダーがない場合、サーバーは標準の Accept-Language ヘッダーを使用し、それもない場合は英語を使用します。エラーのコードは安定した識別子であり、ローカライズされません。分岐には code を使用し、message を表示してください。

エラー

失敗したリクエストは、統一された単一形式の JSON ボディを返します。

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to perform this action",
  "status": 401,
  "detail": { }
}

フィールド	型	意味
`code`	string	安定した機械可読のエラーコード。分岐にはこれを使用します。
`message`	string	人が読める説明。`Dust-Ctx-Locale` に従ってローカライズされます。
`status`	number	HTTP ステータスコードと同じ値です。
`detail`	object（任意）	検証の詳細など、このエラーに関する追加のコンテキストです。

利用初期によく遭遇するコードは次のとおりです。

コード	一般的なステータス	発生条件
`INVALID_REQUEST`	400	ボディ、クエリ、またはヘッダーの形式が不正（検証の詳細は `detail` に格納）。
`UNAUTHORIZED`	401	ベアラートークンがない、期限切れ、または無効。
`FORBIDDEN`	403	認証済みだが、このチームコンテキストではその操作を実行できない。
`NOT_FOUND` / `NO_DATA_FOUND`	404	このコンテキストから参照できる該当記録がない。
`ORG_ID_REQUIRED` / `TEAM_ID_REQUIRED`	400	範囲が指定されたエンドポイントに必要なコンテキストヘッダーがない。
`THREAD_DATA_CONFLICT`	409	楽観的並行性制御の競合。参照していたスレッドの状態が古くなっています。

すべてのレスポンスには x-request-id ヘッダーも含まれます。この値をログに記録し、サポートへの問い合わせ時に添えてください。サーバートレース内で該当リクエストを特定できます。

エラーとスキャン結果には完全なリファレンスがあります。遭遇する可能性のあるすべてのコードとそのステータス、正式な識別結果および検証結果の表、再試行の指針、操作が失敗した場合にスキャンの受領記録を保持する方法を確認できます。

ページネーション

一覧エンドポイント（スレッド、フォルダー、ファイル、イベント、テンプレートなど）では、カーソルページネーションを使用します。

リクエスト：クエリパラメーターとして pageSize（ページの長さ）と cursor（前のページから取得した不透明な文字列）を指定します。pageSize は 1～1,000 の整数である必要があります。一部のエンドポイントでは、より小さい最大値が設定されています。省略すると、エンドポイントのデフォルト値が使用されます。
pageIndex を使用するエンドポイントでは、0～1,000,000 の整数を指定できます。負数または小数のページネーション値は拒否されます。
レスポンス：アイテムの配列と、任意の next および prev カーソル文字列が返されます。next がない場合は、最後のページです。

# First page
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

# Follow the cursor
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50&cursor=$NEXT" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

{
  "threads": [ ... ],
  "next": "eyJjcmVhdGVkQXQiOi...",
  "prev": "eyJjcmVhdGVkQXQiOi..."
}

カーソルは不透明な値です。保存してそのまま再利用し、解析しないでください。並び順をサポートする一覧エンドポイントでは、order（asc/desc）とエンドポイント固有の orderCol（スレッドの場合は createdAt、updatedAt、name）を使用します。

認可レベル

すべての操作には 3 つの権限レベルのいずれかが必要です。パスのプレフィックスを見れば、スキーマを読む前に必要なレベルを判断できます。

プレフィックス	呼び出せるユーザー	備考
`/api/v1/org/*`	組織管理者 — `Dust-Ctx-Org-Id` で指定された組織内で `admin`（または `owner`）ロールを持つユーザー	チームの作成、チームの更新、所属メンバーの管理
`/api/v1/connections/*`	チーム管理者 — `Dust-Ctx-Team-Id` で指定された操作対象チームの管理者	接続のライフサイクルと変更
その他すべて	操作に別段の記載がない限り、リクエストコンテキストのメンバー	標準機能の範囲

各操作には、OpenAPI 仕様内に x-required-role 拡張（member、publisher、team-admin、または org-admin）も含まれています。これを操作ごとの正式なポリシーとして扱ってください。注釈がない操作には member が必要です。publisher は独立した権限レベルではなく、チームへの所属に付与される権限です。チームのデータを公開して読み取り可能にするために必要であり、チーム管理者には常に付与されています。自分の権限レベルを上回る操作を呼び出すと、ペイロードにかかわらず 403 FORBIDDEN が返されます。

ボディ、ID、タイムスタンプ

リクエストの Content-Type は、エンドポイントが multipart フォームデータを明示的に受け取る場合（/api/v1/tags/* での識別子スキャン、ファイルアップロード）を除き、application/json です。
ID は RFC 4122 UUID 文字列（threadId、eventId、組織 ID、チーム ID など）です。不透明な値として扱ってください。
タイムスタンプ（createdAt、updatedAt、archivedAt など）は UTC タイムスタンプ文字列です。
書き込みはイベントとして記録されます。スレッドへの変更では、暗黙に上書きするのではなく、そのイベント履歴にイベントが追加されます。GET /api/v1/threads/{thread_id} のような読み取りは { thread, events } を返します。