File の検索

POST /api/v1/forward/files/search x-qoder-beta: search-2026-08-31 ヘッダーが必須です。検索条件はすべて省略可能で、JSON ボディに指定します。URL クエリに指定した同名の検索パラメーターは無視されます。ただし、帰属を選択する identity_id は例外で、クエリでのみ指定できます。リクエストボディは単一の JSON オブジェクトである必要があります。条件を指定しない場合は {} を使用します。

帰属クエリパラメーター

パラメーター	型	必須	説明
`identity_id`	string	いいえ	Identity に属するリソースを操作する場合にのみ使用します。PAT ではクエリパラメーターとして明示的に指定でき、省略すると管理者 Scope になります。SAT の帰属は認証情報によって決まります。Admin SAT を含むすべての SAT でこのパラメーターを明示的に指定すると、空値でも HTTP 400 が返されます。JSON ボディに指定すると、未知のフィールドとして 400 が返されます。詳細は Identity の帰属を参照してください。

検索条件（JSON ボディ）

パラメーター	型	説明
`metadata`	object<string,string>	metadata の完全一致条件です。複数の条件は AND で結合されます。最大 16 件。
`limit`	integer	ページサイズです。デフォルトは 20、範囲は 1～100。
`page`	string	前のレスポンスの `next_page` で返されたカーソルです。
`name`	string	ファイル名に対する大文字と小文字を区別しない部分一致です。最大 255 文字。
`scope_id`	string	リソースの Scope ID です。現在は Session ID を指定します。

curl -X POST "https://api.qoder.com/api/v1/forward/files/search" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: search-2026-08-31" \
  -d '{"metadata":{"project":"demo"},"name":"report","limit":20}'

レスポンス

フィールド	型	説明
`data`	array	現在のページで Forward から参照可能なリソースの一覧です。リソースのフィールドは対応する一覧取得 API と同じです。
`first_id`	string \| null	現在のページの最初のリソース ID。
`last_id`	string \| null	現在のページの最後のリソース ID。
`has_more`	boolean	Forward から参照可能なリソースの次のページが存在することが確認されているかどうかです。
`next_page`	string \| null	次のページのカーソルです。次のページがない場合は `null`。

{
  "data": [],
  "first_id": null,
  "has_more": false,
  "last_id": null,
  "next_page": null
}

data 内のリソースフィールドは File の一覧取得と同じです。 metadata のキーは 1～64 文字で、空白文字だけにすることはできません。値は最大 512 文字の文字列である必要があります。クライアントは返された next_page をそのまま再送し、カーソルを独自に生成しないでください。

エラー

HTTP	Type	発生条件
400	`invalid_request_error`	Beta ヘッダーまたはリクエストボディがない、または検索パラメーターが不正です。SAT でクエリパラメーター `identity_id` を明示的に指定した場合（空値を含む）も該当します。JSON ボディに `identity_id` を指定した場合も該当します。
401	`authentication_error`	認証トークンがないか、無効です。
403	`permission_error`	管理者 Scope で Owner mismatch が発生したか、下流サービスがアクセスを拒否しました。
404	`not_found_error`	PAT で指定した Identity が存在しない、無効化または削除されている、あるいは呼び出し元に属していません。
429	`rate_limit_error`	Forward または依存サービスのレート制限を超えました。
500/502/503	`api_error`	Forward または依存サービスでエラーが発生しました。

​帰属クエリパラメーター

​検索条件（JSON ボディ）

​レスポンス

​エラー

帰属クエリパラメーター

検索条件（JSON ボディ）

レスポンス

エラー