メインコンテンツへスキップ
POST /api/v1/cloud/files テキストベースのファイルをアップロードし、ファイルオブジェクトを返します。

​
ヘッダー

ヘッダー必須説明
AuthorizationはいBearer $QODER_PAT
Content-Typeはいmultipart/form-data

​
リクエストボディ

フィールド型必須説明
filefileはいテキストベースのファイル内容。サポートされるアップロードファイルタイプを参照
namestringいいえ保存されるファイル名。デフォルトはアップロードされたファイル名。サーバーのサニタイズ後、長さは 1-255 バイトで . や .. は不可
metadataJSON stringいいえフォームフィールドとしてエンコードされた有効な JSON。最大生データ長は 8 KB。デフォルトは {}

​
リクエスト例

curl -X POST "https://api.qoder.com/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./my-document.txt" \
  -F "name=my-document.txt" \
  -F 'metadata={"project":"demo"}'

​
レスポンス例

HTTP 200 OK 
{
  "id": "file_019e3bb8c1387743bf4ef115aae5acb1",
  "type": "file",
  "filename": "my-document.txt",
  "mime_type": "text/plain",
  "size_bytes": 110,
  "downloadable": false,
  "scope": null,
  "metadata": {
    "project": "demo"
  },
  "created_at": "2026-05-18T15:33:44Z"
}

​
レスポンスフィールド

フィールド型説明
idstringファイル ID（file_ プレフィックス）
typestring常に "file"
filenamestring保存されたファイル名
size_bytesintegerファイルサイズ（バイト）
mime_typestringアップロード時に指定された MIME タイプ、またはファイル名から検出された MIME タイプ
downloadablebooleanこのファイルを /content エンドポイント経由でダウンロードできるかどうか
scopeobject | nullファイルが他のリソースに関連付けられている場合のスコープオブジェクト。例: { "id": "sess_...", "type": "session" }
metadataobjectアップロード時に指定するカスタムメタデータオブジェクト。デフォルトは {}
created_atstring作成時刻（RFC 3339 形式の UTC）

​
注意事項

  • multipart リクエストボディはファイルコンテンツ約 5 MB とマルチパートオーバーヘッドに制限されます。
  • テキストベースのファイルのみ受け付けます。バイナリドキュメント、画像、音声、動画、アーカイブファイルは拒否されます。
  • サーバーは name をサニタイズし、ベースファイル名を保持してパスセパレータやヌルバイトを _ に置換します。

​
エラーレスポンス

HTTPtype説明
400invalid_request_errorfile の欠落、無効なマルチパートフォーム、サポートされていないファイルタイプ、無効な name、無効な metadata、またはリクエストボディが大きすぎる
401authentication_error認証トークンが欠落または無効
500api_errorファイルストレージバックエンドが利用不可
エラーで完全なエラーエンベロープを参照してください。

​
関連項目

ファイルの添付とダウンロード

Agent にコンテキストを提供するファイルをアップロードし、Agent が生成したファイルをダウンロードします。