AIエージェントを使った開発

AIコーディングエージェント（Claude Code、Cursor、Copilotなど）を使用してDUSTプラットフォーム向けの開発を行う場合、このページがその入口です。ここにあるものはすべて、エージェントに渡せる安定した公開URLです。

まずはこちら

エージェントに渡すもの	用途
`/skills/dice-api-integration/SKILL.md`	DUST APIの呼び出し：認証、コンテキストヘッダー、スレッド、識別子、ファイル、共有、出荷
`/skills/dust-go-connect-integration/SKILL.md`	DUST Goモバイルアプリ内で実行されるWebアプリへのDUSTスキャン機能の追加
`/llms.txt`	全ページの一覧。エージェントが必要なページを選択できます
`/llms-full.txt`	ドキュメント全体を1つのプレーンテキスト文書にまとめたもの
`/openapi.json`	正確なリクエストおよびレスポンスの契約

エージェントが間違えやすい4つの事実

エージェントのコンテキストにほかの何も読み込ませない場合でも、これらは読み込ませてください。いずれも、APIが黙って許容するのではなくリクエストを拒否するため、間違えると統合が完全に失敗します。

**識別検索のスキャン範囲フィールドはsearchTeamIds**であり、チームUUIDのJSON配列です。searchGroupIdsというリクエストフィールドは存在しません。Identifyのペイロードでは宣言されていないプロパティが拒否されるため、名前を間違えるとリクエスト全体が400 INVALID_REQUESTで失敗します。従来のgroupという名前で唯一残っているのは、Dust-Ctx-Team-Idの別名として受け入れられるDust-Ctx-Grp-Idヘッダーです。
Verifyではtagsが必須であり、オブジェクトの配列です：ID文字列の配列ではなく、[{"tagId": "…", "tagType": "DUST"}]です。multipartボディではJSONとしてエンコードします。
Identifyの不成立は、エラーステータスを伴う回答です。 404 IDENTIFIER_NOT_FOUNDは一致するものがなかったこと、503 SCAN_SEARCH_INCOMPLETEは検索を完了できず再試行すべきこと、400 SCAN_LOW_KEYPOINTSは再スキャンが必要なことを意味します。2xx以外をすべて例外として扱う生成コードは、実際には発生していない障害を報告してしまいます。標準表については、エラーとスキャン結果を参照してください。
認証情報はサーバー内に保持します。 DUST bearer tokenにはService Accountのすべてのアクセス権限が付与されており、ブラウザーセッション向けに権限を限定する仕組みはありません。サポートされる構成は、ブラウザー → 顧客のバックエンド → DUST APIです。DUST tokenをpropとして受け取るコンポーネントは絶対に生成しないでください。

標準例

以下がコピーすべき形式です。どちらのブロックもサーバー上で実行します。

// Identify: which Thread does this capture belong to?
const form = new FormData();
form.set("tagType", "DUST");
form.set("data", captureBlob);                              // binary, not base64
form.set("searchTeamIds", JSON.stringify(allowedTeamIds));  // NOT searchGroupIds

const response = await fetch(`${apidUrl}/api/v1/tags/identify`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Dust-Ctx-Org-Id": organizationId,
    // "Dust-Ctx-Team-Id": teamId,  // optional; omit for the org's root Team
  },
  body: form,
});
const body = await response.json();

if (response.ok) {
  // body.type is "identified" | "matches" | "label"
} else if (body.code === "IDENTIFIER_NOT_FOUND") {
  // An answer: nothing matched. Not a failure.
} else if (body.code === "SCAN_SEARCH_INCOMPLETE") {
  // Retry — the item may well be enrolled.
}

// Verify: is this capture the item it claims to be?
const form = new FormData();
form.set("threadId", threadId);
form.set("tagType", "DUST");
form.set("data", captureBlob);
form.set("tags", JSON.stringify([{ tagId, tagType: "DUST" }])); // required, objects

const response = await fetch(`${apidUrl}/api/v1/tags/verify`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Dust-Ctx-Org-Id": organizationId },
  body: form,
});
const body = await response.json();

// One candidate: a mismatch is an error status.
// Two or more: a mismatch is HTTP 200 with { success: false } — read `success`.

パッケージ依存関係のない、完全かつ実行可能なエンドツーエンドの手順（トークン交換、組織の検出、チームの検出、作成、読み戻し）については、APIクイックスタートを参照してください。

llms.txt

llms.txt規約に従い、サイトのルートでは次のファイルを提供しています。

ファイル	内容
`/llms.txt`	サイトマップ：全ページと各ページの1行説明、およびOpenAPI仕様、インタラクティブリファレンス、npmパッケージへの参照
`/llms-full.txt`	ドキュメントの全内容を1つのプレーンテキスト文書にまとめたもの
`/llms-small.txt`	コンテキストウィンドウが小さい場合に適した縮小版

エージェント自身にページを選ばせる場合は/llms.txtを参照させ、全体像が必要な場合は/llms-full.txtを与えてください。結合されたファイル内のリンクは、その内容の出典であるページとセクションに戻る絶対URLになっているため、エージェントは使用した情報源を引用できます。

OpenAPI仕様

正式なAPIサーフェスは、次のOpenAPI 3文書です。

APIサーバーが提供するライブ版：https://apid.dustid.io/api/openapi.json
このサイトにあるビルド時のコピー：/openapi.json
インタラクティブリファレンス（Scalar）：https://apid.dustid.io/api/docs

このサイトにあるコピーは公開サーフェスです。DUST内部向けの操作は除外されています。実際に呼び出しているサーバーを確実に記述する必要がある場合は、ライブ文書を使用してください。

統合スキル

スキルとは、SKILL.md形式（nameとdescriptionを含むYAML frontmatterの後に手順が続く形式）の単一のMarkdownファイルであり、認証、ヘッダー、主要フロー、失敗時の挙動まで、1つの統合をエージェントに最初から最後まで教えるものです。各スキルは自己完結しており、エージェントはスキルファイルだけで統合を完了できます。

dice-api-integration認証（API key → bearer）、コンテキストヘッダーの設定、主要なAPIフロー（スレッドの作成、識別子のバインド、ファイルのアップロード、共有、出荷）を実行します。ダウンロード

dust-go-connect-integration@dustid/dust-go-connectを使用し、DUST Goモバイルアプリ内でWebアプリからDUST識別子をスキャンできるようにします。ダウンロード

スキルのインストール

上記の安定したURL（例：/skills/dice-api-integration/SKILL.md）からスキルファイルをダウンロードします。
Claude Codeの場合は、プロジェクト内の.claude/skills/dice-api-integration/SKILL.mdに配置します（ディレクトリ名はスキルのnameと一致させます）。Claudeはこれを自動的に検出し、タスクが一致すると読み込みます。
その他のエージェントの場合は、そのファイルをエージェントのコンテキストまたはシステムプロンプトに含めます。このファイルはプレーンなMarkdownであり、自己完結しています。

「生成済み」が意味すること、意味しないこと

各スキルファイルには、ドキュメントのバージョン、OpenAPI仕様のバージョン、仕様内のパス数、およびそのファイルの生成元となった正確な公開仕様のダイジェストを示す来歴ブロックがあります。この4つの情報により、手元のコピーがどの時期のAPIを説明しているのか、また2つのコピーが同じ仕様から生成されたものかを判断できます。

それによって保証される内容を正確に理解してください。

スキルの部分	出所	古くなる可能性があるもの
`dice-api-integration`内のエンドポイントインデックス	ビルド時に公開OpenAPI仕様から生成	なし — 仕様自体のパス、メソッド、概要です
バージョンとダイジェストの行	ビルド時に生成	なし
その他すべて：認証手順、パラメーター名、ペイロード形式、SDKの挙動、失敗時の処理	手書き	対応するドキュメント編集を伴わずにAPIで変更されたものすべて

生成コードの確認

エージェントが生成したものを人が確認するための短いチェックリストです。

すべてのパスとメソッドが仕様に記載されている。架空のエンドポイントがない。
/api/v1/*の呼び出しにAuthorization: Bearerが含まれ、組織を範囲とするすべての呼び出しにはDust-Ctx-Org-Idも含まれている。
IdentifyでsearchGroupIdsではなく、必ずsearchTeamIdsを送信している。
Verifyでtagsを{ tagId, tagType }オブジェクトの配列として送信している。
エラー処理がmessageのテキストではなくcodeで分岐し、「一致なし」「再試行」「再スキャン」を区別している。
ブラウザーまたはモバイルクライアントに配布されるものに、API keyやbearer tokenが含まれていない。
スキャン受領情報（scan.scanId、失敗時はdetail.scan.scanId）が記録されている。
401で実行する更新と再試行が1回だけで、ループになっていない。

npmパッケージ

@dustid/dust-go-connect — Webアプリ向けのDUST Goスキャンブリッジです（DUST Goとの統合を参照）。
@dustid/apid-client — 型付きTypeScript APIクライアントです。公開npmレジストリでは提供されていません。利用可否と前提条件については、TypeScriptクライアントを参照してください。エージェントは、このパッケージのインストールコマンドを出力すべきではありません。

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