コアモデル

DUST プラットフォーム API は、物理オブジェクトのワークフローを、組み合わせ可能な少数のリソースとしてモデル化します。スレッドは物理アイテムのデジタル記録です。識別子、ファイル、フォルダー、アセンブリー、共有、出荷など、その他のすべての要素は、スレッドへの関連付け、整理、または移動を担います。このページは全体像を示すマップです。概念ごとに短いセクションを設け、主要なエンドポイントと詳しいガイドへのリンクを掲載しています。

名称対応表

一部の API 名前空間は、現在の製品用語より前から存在します。DICE Web アプリとこのドキュメントでは左列の名称を使用しますが、API パスでは右列の名称が維持されています。

DICE / ドキュメントでの名称	API 名前空間	注記
スレッド	`/api/v1/threads`	—
識別子	`/api/v1/tags`	パスでは従来の `tags` という名称を使用
ファイル	`/api/v1/files`	一部のスキーマではリソースと呼ばれます
フォルダー & カテゴリー	`/api/v1/bundles`	実装上の名称はバンドルです
アセンブリー	`/api/v1/assemblies`	アセンブリーは `assembly` kind のスレッドです
チーム	`/api/v1/teams`	リクエストごとに `Dust-Ctx-Team-Id` ヘッダーで選択します（従来の `Dust-Ctx-Grp-Id` も引き続き使用できます）
接続	`/api/v1/connections`	Wire スキーマでは従来のチームリンクという名称が維持されています
共有	`/api/v1/sharing`	—
出荷	`/api/v1/transfers`	パスでは従来の `transfers` という名称を使用
分割	`/api/v1/slices`	—
Fabric	`/api/v1/fabric`	組織横断の来歴グラフ
証明書	`/api/v1/certificates`, `/api/v1/certificate-forms`	—
公開ページ	`/api/v1/public-pages`, `/api/v1/public-page-designs`	公開にはチームの `publisher` 権限が必要です
イベント	`/api/v1/events`	—

すべてのリクエストには AuthD ベアラートークンを指定します。組織を範囲とするエンドポイント（ほぼすべてのエンドポイント）では、さらに Dust-Ctx-Org-Id ヘッダーを追加します（必要に応じて、チームを選択するために Dust-Ctx-Team-Id も指定します）。認証と規約を参照してください。パラメーター単位の完全なリファレンスについては、API リファレンスを参照してください。

スレッド

スレッドは、1 つの物理資産、部品、文書、またはワークフローアイテムを表す記録です。名前と説明、型付きフィールドデータ、添付ファイル、バインド済みの識別子、イベント履歴で構成されます。スレッドには kind があり、通常のユニットまたは assembly（後述）を指定します。

POST /api/v1/threads — 1 つまたは複数を作成
GET /api/v1/threads — 検索および一覧取得（カーソルページネーション）
GET /api/v1/threads/{thread_id} — フィールドデータを含む 1 件を取得
POST /api/v1/threads/{thread_id}/data — フィールド値を upsert または削除
PATCH /api/v1/threads/archive / PATCH /api/v1/threads/restore — アーカイブのライフサイクル

詳細：スレッド API ガイド。

フィールドとテンプレート

フィールド値には型があり（text、number、date、select、リソース参照、さらにはスレッドを値とするフィールド）、型ごとにネストされています。テンプレートは、繰り返し使用する種類のスレッドに必要なフィールドを定義します。

POST /api/v1/templates / GET /api/v1/templates — テンプレートの作成と一覧取得
GET /api/v1/templates/{templateId} / PATCH /api/v1/templates/{templateId} — 読み取りと更新

識別子

識別子は、DUST タグ、QR コード、バーコード、Data Matrix シンボル、NFC チップなどの物理的なマーキングをスレッドにバインドします。これにより、現場でのスキャンからデジタル記録を解決できます。API 名前空間は /api/v1/tags です（従来の名称）。

POST /api/v1/tags/extract — DUST 撮影データを解析し、バインドせずに正規化されたフィンガープリントを抽出
POST /api/v1/tags/bind — 識別子をスレッドにバインド
POST /api/v1/tags/identify — スキャンに一致するスレッドを検索
POST /api/v1/tags/verify — スキャンが特定のスレッドの識別子と一致することを検証
POST /api/v1/tags/unbind — 識別子のバインドを解除

詳細：識別子 API ガイド。

ファイル

ファイル（一部のスキーマではリソースと呼ばれます）はオブジェクトストレージに保存され、スレッドに直接、またはリソース型フィールドを介して添付されます。大容量ファイルのアップロードには再開可能な tus プロトコルを使用し、小容量ファイルには単一の multipart POST を使用します。

POST /api/v1/files — シンプルな multipart アップロード
POST /api/v1/files/finalize — 完了した tus アップロードをリソース記録に変換
GET /api/v1/files/{resource_id}/download — ダウンロード
POST /api/v1/files/urls — 有効期間の短い署名付き URL
GET /api/v1/files/search — ファイル横断検索

詳細：ファイル API ガイド。

チームと組織

Identity は AuthD で管理されます。プラットフォーム API はコンテキストヘッダーを使用して、組織を範囲とする各リクエストを組織とチームに限定します。チームはスレッドを所有し、共有、接続、出荷はすべてチーム間で行われます。

GET /api/v1/me — 現在のユーザーと利用可能な組織
GET /api/v1/teams — 呼び出し元から参照できるチーム
POST /api/v1/org/teams / PATCH /api/v1/org/teams/{team_id} — チーム管理（組織管理者）
POST /api/v1/org/teams/members — メンバーシップ管理（組織管理者）

詳細：チーム、共有、接続。

フォルダーとカテゴリー

フォルダーとカテゴリーはスレッドを整理します。API ではどちらもバンドルです。排他的に格納する場合は kind: "folder"、非排他的にラベル付けする場合は kind: "category" を使用し、バンドルをネストしてツリーを形成します。

POST /api/v1/bundles — 作成（kind と、任意で親を示す childOfId を指定）
GET /api/v1/bundles / GET /api/v1/bundles/children — 一覧取得、またはツリーの遅延走査
POST /api/v1/bundles/{bundle_id}/add / PATCH /api/v1/bundles/{bundle_id}/move — スレッドを配置
PATCH /api/v1/bundles/parent — バンドルの親を変更

アセンブリーと部品

アセンブリーは assembly kind のスレッドで、その部品は別のスレッドです。これにより部品表の構造を表します。部品が取り外されないよう保護でき、部品リストは推移的に集約できます。

GET /api/v1/assemblies — アセンブリースレッドの一覧取得
POST /api/v1/assemblies/{assembly_id}/parts / DELETE /api/v1/assemblies/{assembly_id}/parts — 部品の取り付けと取り外し
GET /api/v1/assemblies/{assembly_id}/rolled-up-parts — 推移的な部品リスト
PATCH /api/v1/assemblies/{assembly_id}/kind — スレッドを unit と assembly の間で変換
POST /api/v1/imports/plan / POST /api/v1/imports/commit — アセンブリーのインポートパッケージ全体をドライランしてコミット

スレッドのリンクと関係

スレッドは型付きリンクで互いを参照できます。関係定義は関係の種類に名前を付け、スレッドリンクはそのインスタンスを表します。

POST /api/v1/relations / GET /api/v1/relations — 関係の種類を定義して一覧取得
POST /api/v1/links / GET /api/v1/links — スレッド間のリンクを作成して一覧取得
GET /api/v1/threads/{thread_id}/links — 1 つのスレッドを基点としたリンク
DELETE /api/v1/links/{link_id} — リンクを解除

共有では、別のチームにスレッドまたはバンドルへの viewer または editor アクセス権を付与します。権限は関係タプルとして保存され、アクセス概要には継承されたアクセス権を含む実効結果が表示されます。

POST /api/v1/sharing — スレッドまたはバンドルをチームと共有
GET /api/v1/sharing — 権限の一覧取得（direction=in|out）
GET /api/v1/sharing/access-summary — 1 つのオブジェクトに対する実効アクセス権
GET /api/v1/sharing/partner-inventory — 1 つのパートナーチームと共有されているすべてのもの

詳細：チーム、共有、接続。

接続

接続（API：チームリンク）は、2 つのチーム間（多くの場合は異なる組織間）で結ぶ継続的な合意です。許可されるデータフローの方向を定め、共有と出荷を可能にします。招待、承諾、確認のハンドシェイクと、一時停止、再開のライフサイクルがあります。

POST /api/v1/connections — 作成（招待）
PATCH /api/v1/connections/accept / confirm / reject / cancel — ハンドシェイク
PATCH /api/v1/connections/pause / resume — 一時停止と再開
POST /api/v1/connections/amend/propose — 方向変更を提案

出荷

出荷（API：transfer）は、スレッドの所有権をあるチームから別のチームへ移します。下書きの明細書を作成して送信し、受信側は承諾、拒否、または変更要求を行います。

POST /api/v1/transfers — 下書きを作成
POST /api/v1/transfers/{transfer_id}/items — 明細書のアイテムを追加
POST /api/v1/transfers/{transfer_id}/send — 受信側のチームへ送信
POST /api/v1/transfers/{transfer_id}/respond — 承諾 / 拒否 / 変更要求
GET /api/v1/transfers — 受信トレイ、送信トレイ、送信済みビュー

セマンティクスとライフサイクル：出荷。エンドポイントの概要はチーム、共有、接続を参照してください。

分割

分割は、同じチーム内の既存のスレッドから新しいスレッドを派生させます。選択したフィールド、ファイル、識別子をコピーまたはリンクし、通常は共有可能なサブセットを準備するために使用します。

POST /api/v1/slices — 1 つのスレッドを分割
POST /api/v1/slices/batch — 複数のスレッドを一括で派生
GET /api/v1/slices/{slice_id} — Fabric リンクを含む分割

Fabric

Fabric は組織横断の来歴レイヤーです。スレッドがチームの境界を越えて移動または開示されると、Fabric はリンクされたスレッドのグラフを記録し、下流の各関係者が参照できるデータをリビジョンごとに厳密に制御します。

GET /api/v1/fabric/threads/{thread_id}/graph — スレッドから参照できる来歴グラフ
GET /api/v1/fabric/links/{link_id}/context — リンク上で現在開示されているデータ
POST /api/v1/fabric/threads/{thread_id}/disclosure/revise / redact — 開示内容を変更
POST /api/v1/fabric/threads/{thread_id}/disclosure/push — 開示を下流へプッシュ
GET /api/v1/fabric/notifications — 下流の所有者に対する開示通知

概念：Fabric。

証明書

証明書は、スレッドデータを発行済みの検証可能な文書としてレンダリングします。証明書フォームはレイアウトであり、生成時にはフィールド名によってフォームをスレッドにバインドします。

フォームには複数の Vlink QR ゾーンを含められます。証明書の生成では、ゾーン識別子ごとに 1 つの Vlink 設定を受け取り、発行されたすべてのゾーンと Vlink の関連付けを返します。

POST /api/v1/certificate-forms / GET /api/v1/certificate-forms — フォームを管理
POST /api/v1/certificates/preflight — フォームをスレッドに対して解決できるか事前確認
POST /api/v1/certificates/generate — 証明書を発行
GET /api/v1/certificates — スレッドの証明書を一覧取得
POST /api/v1/certificates/void — 1 件を無効とする

概念：証明書。

公開ページ

公開ページは、認証なしで閲覧できるスレッドの Web ビューです。消費者が識別子をスキャンしてアクセスするデジタル製品パスポートに相当します。表示内容は、再利用可能でチームが所有する公開ページデザインによって完全に決まります。そのため、公開時にスレッドごとのコンテンツを入力する必要はなく、スレッドに対してデザインが解決されます。ページの URL は、何かを公開する前に予約してバインドされるため、先にラベルを印刷できます。

デザインを公開すると、変更不能なデザインバージョンとして固定されます。各ページは、1 つのデザインバージョンと 1 つのデータスナップショット（そのスレッドについて解決された値）に固定されます。一括公開では、フォルダー、カテゴリー、テンプレート、または明示的な選択を範囲として、その中のすべてのページを 1 つのデザインバージョンで再公開します。これは独自の進捗状況と失敗件数を記録するバックグラウンド実行として処理されます。

ページ URL の予約とスレッドへのバインドにはメンバー権限レベルが必要です。アドレスを予約しても何も公開されないため、公開を決定する前にラベルを印刷できます。データを公開状態にするすべての操作（ページの公開、アクティベートまたはアーカイブ、デザインの作成、デザインバージョンの公開、展開、一括公開）には、チームの publisher 権限が必要です（チーム管理者にはこの権限が含まれます）。事前確認とプレビューの確認にも同じ権限が必要です。各操作に必要な権限については、API リファレンスの x-required-role が正式な情報です。

POST /api/v1/public-pages / POST /api/v1/public-pages/{publicPageId}/bind — 永続的なページ URL を予約し、スレッドにバインド
GET / PUT /api/v1/public-pages/thread/{threadId} — スレッドのページを読み取る、または取得して、存在しなければ作成
GET /api/v1/public-pages/thread/{threadId}/activity — 公開ページでの匿名閲覧と検証スキャン
POST /api/v1/public-pages/{publicPageId}/publish — デザインの最新バージョンを通じてスナップショットを公開
PATCH /api/v1/public-pages/{publicPageId} — URL を変更せずにページをアクティベートまたはアーカイブ
GET /api/v1/public-pages/{publicPageId}/publications — 公開履歴
POST /api/v1/public-pages/preflight / preflight/batch — 1 つまたは複数のスレッドに対してデザインを解決できるか事前確認
POST /api/v1/public-page-designs / GET / PATCH /api/v1/public-page-designs/{designId} — デザインの下書きを作成
POST /api/v1/public-page-designs/{designId}/versions — デザインバージョンを公開（GET で一覧取得）
POST /api/v1/public-pages/designs/{designId}/roll-out — デザインの最新バージョンを、そのデザインを使用する各ページへ展開
POST /api/v1/public-pages/waves — 一括公開を開始（GET で実行記録、アイテム、一覧を取得）
POST /api/v1/public-pages/waves/{waveId}/retry-failed / cancel — 失敗した処理を再試行、または残りの処理を停止

展開は前方にのみ進みます。デザインバージョンが復元されることはなく、一括公開をキャンセルしても、すでに公開されたページには受け取ったバージョンが維持されます。

概念：公開ページ。

イベント

フィールドの編集、バインド、共有、出荷など、意味のあるすべての変更はイベントとして記録され、DICE で取引ログとして表示される監査証跡を形成します。

GET /api/v1/events — イベントを一覧取得。スレッド、チーム、アクション、時刻で絞り込め、任意でアクティビティをグループ化できます（groupBy）
- lineage=upstream（threadId と併用）を指定すると、そのスレッドの Fabric 系譜上にあるすべての以前のスレッドのイベントも返されます。つまり、受け取ったスレッドの完全なストーリーが、各ソースが開示した範囲内で取得できます。上流の行には lineage オブジェクト（ソースのスレッド、ソースのチーム、リンク、ホップ）が含まれ、redacted となる場合があります。ソースが後から開示内容を変更すると、読み取り専用の fabric.disclosure.revised 行として表示されます。省略した場合、レスポンスにはそのスレッド自身のイベントのみが含まれます。
- resourceId、tagId、fieldId（いずれか 1 つを threadId と併用）を指定すると、履歴を 1 つのファイル、識別子、またはフィールドに限定できます。証明書はそのファイルで指定します。lineage=upstream と併用すると、そのアセット自身の系譜がたどられます。
- 出荷で受け取ったスレッドや分割によって作成されたスレッドの履歴は、transfer.received / slice.derived から始まり、受け入れまたは分割を行った人に帰属します。そのスレッド自身の created.thread や bind は含まれません。
GET /api/v1/summary — 主要な件数指標
GET /api/v1/notifications — 呼び出し元への通知

次のステップ

クイックスタート

クイックスタートで、最初の認証済み呼び出しを実行します。

TypeScript クライアント

生の HTTP の代わりに、型付きの @dustid/apid-clientを使用します。

規約

ヘッダー、ページネーション、エラーについては、API 規約を参照してください。

完全なリファレンス

すべてのパス、パラメーター、スキーマについては、API リファレンスを参照してください。

PDF 記録票

GET /api/v1/receipts/{kind}/{id} を使用して、必要に応じて PDF をダウンロードできます。kind は file、thread、shipment のいずれかで、id は対応する UUID です。通常の認証と、アクティブな組織およびチームのコンテキストヘッダーを使用してください。レスポンスは application/pdf で、添付ファイル名と private、no-store のキャッシュ設定が含まれます。Accept-Language で記録票の言語を選択します。

ファイルの記録票には、メタデータ、利用可能な場合は保存済みの SHA-256 チェックサム、関連するスレッドの情報、閲覧が許可された取引ログのエントリーが含まれます。スレッドの記録票には、フィールド、識別子、ファイルとチェックサム、関係、アセンブリーと系譜の情報、閲覧が許可されたログが含まれます。出荷の記録票では、最初に出荷情報、現在の状態、明細書が表示され、その後に閲覧可能なスレッドの詳細とログが続きます。保留中の出荷では提示されたスナップショットを使用し、それ以外の状態では呼び出し元が現在アクセスできる記録を使用します。

開示を通じて閲覧できるファイルには linkId を指定し、保留中の出荷で提示されているファイルには transferId を指定します。これらの任意の UUID クエリパラメーターは併用できず、ファイルの記録票にのみ適用されます。対応するプレビューと同じアクセス制限および開示制限が適用されます。

記録票には生成日時と DICE への QR リンクが含まれます。呼び出し元が閲覧できる記録の未署名スナップショットであり、デジタル署名ではありません。生成は読み取り専用で、記録票の添付ファイルや取引ログのイベントは保存されません。1 つのログに含まれる閲覧可能なイベントが 10,000 件を超えるエクスポートは、無断で切り詰められるのではなく失敗します。記録票のリンクにも DICE へのアクセスが必要です。

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