Files API ガイド

ファイル（一部のスキーマではリソースと呼ばれます）には、スレッドに添付される証拠（画像、PDF、文書、スキャン生成物）が格納されます。ファイルはスレッドに直接添付することも、リソース型フィールドの値として添付することもできます。

アップロード方法は、小さなファイル向けのシンプルな単発 POST と、大きなファイル向けの再開可能な tus プロトコルの 2 つです。完全なスキーマについては、API リファレンスを参照してください。

エンドポイント一覧

操作	メソッドとパス
シンプルアップロード	`POST /api/v1/files`
再開可能なアップロード（tus）	`POST /api/v1/files/upload`、続いて `PATCH /api/v1/files/upload/{id}`
tus アップロードの確定	`POST /api/v1/files/finalize`
ダウンロード	`GET /api/v1/files/{resource_id}/download`
署名付き URL	`POST /api/v1/files/urls`
ファイルの検索	`GET /api/v1/files/search`
ファイルの一覧取得（カーソル）	`GET /api/v1/files`
スレッドのファイル一覧取得	`GET /api/v1/threads/{thread_id}/files`

ファイルのリクエストには、選択したチームの現時点でのメンバーシップが必要であり、そのチームは選択した組織に所属している必要があります。これはユーザーとサービスアカウントの両方に適用されます。スレッドへのアップロードには編集アクセス権が必要です。非公開アップロードでは対象としてスレッドを指定する必要があり、その非公開アセットを管理する権限も必要です。未添付のファイルは、非公開でない場合に限り、そのファイルを所有するチームだけが読み取れます。

シンプルアップロード

1 回のリクエストで無理なく送信できるファイルの場合は、file と任意の添付先を指定した multipart/form-data を POST します。レスポンスには、作成されたリソースと署名付き URL が含まれます。

curl
TypeScript

curl -fsS "$APID_URL/api/v1/files" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -F "file=@inspection-report.pdf" \
  -F "threadId=$THREAD_ID"

const resources = await client.files.upload({
  file,               // a File
  threadId,           // optional: attach to a Thread
  // fieldId,         // optional: attach as a field value
  // isPrivate: true, // optional
});

fieldId はファイルをリソース型フィールドの値として添付します。isPrivate は可視性を制限します。

再開可能なアップロード（tus）

大きなファイルでは、/api/v1/files/upload で tus 1.0 再開可能アップロードプロトコルを使用した後、完了したアップロードをリソース記録に変換するための確定呼び出しを行います。処理の流れは、アップロード → 確定 →（すでに添付済み、またはフィールドを介して添付）です。

アップロードを作成します。 tus ヘッダーを指定して POST します。Upload-Metadata の値は base64 でエンコードされ、filename は必須です（fieldId、threadId、isPrivate は任意です）。
Terminal window
```
curl -i -X POST "$APID_URL/api/v1/files/upload" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: 52428800" \
  -H "Upload-Metadata: filename $(printf 'video.mp4' | base64),threadId $(printf %s "$THREAD_ID" | base64)"
# → 201 Created
# → Location: …/api/v1/files/upload/<upload-id>
```
確定処理のために、Location の <upload-id> を保持してください。最終レスポンスでは永続的なリソース ID が返されますが、これはアップロード ID と異なる場合があります。対象のスレッド、フィールド、公開範囲は作成時に指定してください。これらは確定処理中には変更できません。Upload-Length には、既知の正のバイト数を指定する必要があります。
バイト列を送信します（再開可能です。PATCH を繰り返すと Upload-Offset から続行されます）。
Terminal window
```
curl -i -X PATCH "$APID_URL/api/v1/files/upload/$UPLOAD_ID" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Offset: 0" \
  -H "Content-Type: application/offset+octet-stream" \
  --data-binary @video.mp4
```
アップロードリクエストでは、比較的長いアイドル時間が許容されます。中断後に再開するには、同じ URL に HEAD リクエストを送信して現在の Upload-Offset を読み取り、その位置から PATCH します。任意の tus 1.0 クライアントライブラリ（例：tus-js-client）を使用すれば、このプロトコルによる通信を処理できます。
確定します。 アップロードは、確定処理後にのみリソース記録になります。
Terminal window
```
curl -fsS "$APID_URL/api/v1/files/finalize" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "'"$THREAD_ID"'",
    "requests": [
      { "resId": "'"$UPLOAD_ID"'", "filename": "video.mp4", "size": 52428800 }
    ]
  }'
```
POST /api/v1/files/finalize は一度に複数のアップロードを受け付けます。各リクエストアイテムでは、tus アップロード ID を resId として指定し、さらに filename と size を指定します（fieldId と isPrivate は任意です）。ファイル名、サイズ、スレッド、フィールド、公開範囲は、アップロード作成リクエストと一致している必要があります。作成、チャンク送信、HEAD、DELETE、確定処理では、同じ認証済みアイデンティティと組織／チームのコンテキストを使用してください。アップロードセッションは作成から 7 日後に期限切れになります。完了済みのアップロードのみ確定できます。

その期間内に同一内容で確定処理を再試行すると、新しい署名付き URL とともに元のリソースが返されます。バッチに含めることができるのは、新規の完了済みアップロードのみ、または確定済みアップロードのみのいずれかです。確定済みのアップロードに tus を介してパッチを適用したり、終了させたりすることはできません。

ダウンロードと署名付き URL

GET /api/v1/files/{resource_id}/download — ファイルの署名付き URL にリダイレクトします。
POST /api/v1/files/urls?ids=<id>&ids=<id> — オブジェクトストレージへ直接アクセスするための短期間有効な署名付き URL を発行します。ブラウザーまたは後続システムがプロキシを経由せずにバイト列を必要とする場合に使用してください。

検索と一覧取得

クエリには 2 つの形式があります。

GET /api/v1/files/search — q、threadId、mimeFilters、includeArchived を使用する、ページインデックス方式の検索です。
GET /api/v1/files — threadId または createdBy で絞り込む、カーソルページネーション方式の一覧取得（cursor、pageSize。includeArchived は必須）です。

1 つのスレッドのコンテキストにあるファイルについては、GET /api/v1/threads/{thread_id}/files を使用することを推奨します（スレッドガイドを参照してください）。

スレッド API ガイド — スレッドのフィールドとサムネイルへのファイルの添付
コアモデル — ドメイン内でのファイルの位置付け
API リファレンス — パラメーターとスキーマの完全な詳細

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