スレッド API ガイド

スレッドは、資産、部品、文書、ワークフローのアイテムなど、1 つの物理的なアイテムに対応するデジタル記録です。名前と説明、型付きフィールドデータ、添付ファイル、バインド済みの識別子、イベント履歴を保持します。スレッドはチームによって所有されるため、すべてのリクエストに Bearer トークンと Dust-Ctx-Org-Id ヘッダーが必要です（特定のチームとして操作する場合は Dust-Ctx-Team-Id も必要です）。詳しくは認証と規約を参照してください。

このガイドでは主なフローを説明します。すべてのパラメーターとレスポンススキーマについては、API リファレンスを参照してください。

エンドポイント一覧

操作	メソッドとパス
1 つまたは複数のスレッドを作成	`POST /api/v1/threads`
スレッドを一覧表示／検索	`GET /api/v1/threads`
スレッド数を取得	`GET /api/v1/threads/count`
1 つのスレッドを取得	`GET /api/v1/threads/{thread_id}`
メタデータとフィールドを更新	`POST /api/v1/threads/{thread_id}`
フィールドのみを更新	`POST /api/v1/threads/{thread_id}/data`
アーカイブ済みフィールドデータを一覧表示	`GET /api/v1/threads/{thread_id}/data/archived`
アーカイブ済みフィールドデータを復元	`POST /api/v1/threads/{thread_id}/data/restore`
スレッドをアーカイブ	`PATCH /api/v1/threads/archive`
スレッドを復元	`PATCH /api/v1/threads/restore`
呼び出し元の権限を確認	`POST /api/v1/threads/permissions`
プレゼンスのハートビート	`POST /api/v1/threads/{thread_id}/presence`
スレッドのファイルを一覧表示	`GET /api/v1/threads/{thread_id}/files`
サムネイルを設定／アップロード	`PATCH` / `POST /api/v1/threads/{thread_id}/thumbnail`

サムネイルの更新では、認可済みの resourceId、またはデコード後のサイズが最大 5 MiB のラスター画像をインライン base64 形式で格納した imageUri を使用できます。リモート画像 URL は拒否されます。ファイルのアップロードには、引き続きサムネイルアップロードエンドポイントを使用できます。リソースを参照するサムネイルには、参照元リソースの現在の読み取り権限が適用されます。アクセスが拒否された場合、または参照元が添付されなくなった場合、レスポンスでは thumbnail と thumbnailId の両方が null になります。参照元リソースのないアップロード済みサムネイルには、スレッドの表示範囲が適用されます。

スレッドを作成する

POST /api/v1/threads は、type で選択する 3 種類のボディ形式を受け付けます。single（1 つのスレッド）、list（正規化済みの複数のスレッド）、raw（フラットなキーと値の記録）です。いずれも、フォルダー内にスレッドを作成するための省略可能な bundleId を受け付けます。

curl
TypeScript

curl -fsS "$APID_URL/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "thread": { "name": "Tire SZ3J-11-ZJ17" },
    "data": [
      { "name": "Serial Number", "type": "text", "value": { "text": "SZ3J-11-ZJ17" } },
      { "name": "Max PSI", "type": "number", "value": { "number": 51 } }
    ]
  }'

const created = await client.threads.create({
  type: "single",
  thread: { name: "Tire SZ3J-11-ZJ17" },
  data: [
    { name: "Serial Number", type: "text", value: { text: "SZ3J-11-ZJ17" } },
    { name: "Max PSI", type: "number", value: { number: 51 } },
  ],
});

フィールド値は型ごとに value の下へネストされます。たとえば { "text": … }、{ "number": … } などです。仕様では、テキスト、長文テキスト、数値、真偽値、日付、日付範囲、日時、時刻、期間、メール、電話番号、URL、JSON、単一選択、複数選択、タグ、リソース（ファイル）参照、スレッド参照の入力を定義しています。

一括インポート

正規化済みの { thread, data } オブジェクトがすでにある場合は type: "list" を使用します。フラットな記録を API に渡す場合は type: "raw" を使用します。この場合、API は各オブジェクトのキーと値のペアからフィールドを生成し、nameKey と descriptionKey（デフォルトは name / description）をスレッド自体のメタデータとして使用します。

{
  "type": "raw",
  "nameKey": "serial",
  "raw": [
    { "serial": "SZ3J-11-ZJ17", "part": "P355/30R19", "maxPsi": 51 }
  ]
}

アセンブリー構造全体をアトミックにインポートする方法については、リファレンスの POST /api/v1/imports/plan と POST /api/v1/imports/commit を参照してください。

スレッドを読み取る

GET /api/v1/threads/{thread_id} は、フィールドデータを含むスレッドを返します（省略可能な maxEvents クエリを指定すると、最近のイベントも含まれます）。GET /api/v1/threads はカーソルページネーション（cursor、pageSize、order、orderCol）で一覧を返し、次のようなフィルターをサポートします。

フィルター	意味
`q`, `queryCol`	テキスト検索。必要に応じて 1 つの列に限定可能
`bundleId`	フォルダーまたはカテゴリー内のスレッド
`templateId`	テンプレートから作成されたスレッド
`tagType`	この種類の識別子がバインドされているスレッド
`hasResources`	ファイルが添付されているスレッド
`includeArchived`, `archivedOnly`	アーカイブの表示範囲
`createdBy`, `ownedByTeam`	来歴フィルター
`excludeTransferred`, `transferredOnly`	出荷済みのスレッド
`withActiveShipment`	アクティブな出荷がある場合、各アイテムにその出荷の情報を付加

GET /api/v1/threads/count は同じフィルターを受け取り、件数のみを返します。ダッシュボードやページネーションの概要に便利です。

スレッドを更新する

目的別に 2 つのエンドポイントがあります。

POST /api/v1/threads/{thread_id} — { thread, update?, remove? } を受け取ります。スレッドのメタデータ（名前、説明、テンプレートなど）と、省略可能なフィールド変更を 1 回の呼び出しで処理します。
POST /api/v1/threads/{thread_id}/data — フィールドのみを処理し、{ threadId, update, remove?, expectedUpdatedAt? } を受け取ります。update 内のフィールドは upsert され（名前／ID で照合）、remove にはフィールド ID を指定します。

{
  "threadId": "9f6a…",
  "update": [
    { "name": "VIN", "type": "text", "value": { "text": "1HGCM82633A004352" } }
  ],
  "remove": []
}

アーカイブ済みフィールドデータ

フィールドを取り除くと、破棄されるのではなくアーカイブされます。GET /api/v1/threads/{thread_id}/data/archived はアーカイブ済みフィールドを一覧表示し、POST /api/v1/threads/{thread_id}/data/restore は ID を指定してフィールドを復元します（{ threadId, restore: ["field-id", …] }）。

スレッドをアーカイブおよび復元する

アーカイブは一括で実行でき、元に戻せます。

PATCH /api/v1/threads/archive — { threadIds: […], toggle? }。toggle: true を指定すると、リスト内のアーカイブ済みスレッドはアーカイブ解除され、アクティブなスレッドはアーカイブされます。これらは 1 回の呼び出しで実行されます。
PATCH /api/v1/threads/restore — アーカイブ済みスレッドを復元します。

アーカイブ済みスレッドはデフォルトの一覧には表示されません。表示するには includeArchived または archivedOnly を使用してください。

権限

編集コントロールを表示したり、複数のスレッドに対する書き込みを試みたりする前に、呼び出し元が実際に実行できる操作を確認します。

curl -fsS "$APID_URL/api/v1/threads/permissions" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "threadIds": ["9f6a…", "c2d1…"] }'

POST /api/v1/threads/permissions は、現在のチームコンテキストにおける呼び出し元の実効権限をスレッドごとに返します。関連する読み取りエンドポイントとして、GET /api/v1/threads/{thread_id}/access（アクセスを提供するチーム）と GET /api/v1/threads/{thread_id}/shared（スレッドの共有相手）があります。どちらもチーム、共有、接続で説明しています。

プレゼンス

POST /api/v1/threads/{thread_id}/presence はハートビートです。ユーザーがスレッドを表示している間、定期的に送信してください。必要に応じて表示用の name / image を含め、退出時には leaving: true を指定できます。レスポンスには、そのスレッドを現在表示しているユーザーの一覧が含まれます。DICE はこれを「ほかに誰がここにいるか」を示すインジケーターに使用します。

ファイルとサムネイル

ファイルはファイル APIを通じてスレッドに添付します。スレッド側の読み取りエンドポイントは次のとおりです。

GET /api/v1/threads/{thread_id}/files — スレッドのファイルをカーソルページネーションで返します（includeArchived は必須です）。
GET /api/v1/threads/{thread_id}/files/{res_id} / POST …/files/{res_id} — 添付された単一のファイルを読み取り、更新します。
POST /api/v1/threads/{thread_id}/thumbnail — 画像（multipart の thumbnail フィールド）をアップロードし、1 回の操作でスレッドのサムネイルとして設定します。
PATCH /api/v1/threads/{thread_id}/thumbnail — 既存のリソース ID または画像 URI からサムネイルを設定します。

コアモデル — スレッドとほかのすべての要素との関係
識別子 API ガイド — 物理的な識別子をスレッドにバインドする方法
ファイル API ガイド — アップロードとダウンロード
API リファレンス — 上記すべてのエンドポイントの完全なスキーマ

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