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

​
ヘッダー

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

​
リクエストボディ

フィールド型必須説明
filefileはいテキストベースのファイル内容。サポートされるアップロードファイルタイプを参照
namestringいいえ保存されるファイル名。デフォルトはアップロードされたファイル名。サーバーのサニタイズ後、長さは 1-255 バイトで . や .. は不可
purposestringいいえファイル用途。デフォルトは user_upload。ファイル用途を参照
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 "purpose=user_upload" \
  -F 'metadata={"project":"demo"}'

​
レスポンス例

HTTP 201 Created 
{
  "created_at": "2026-05-18T15:33:44Z",
  "file_id": "file_019e3bb8c1387743bf4ef115aae5acb1",
  "filename": "my-document.txt",
  "metadata": {
    "project": "demo"
  },
  "mime_type": "text/plain",
  "purpose": "user_upload",
  "size_bytes": 110,
  "status": "ready",
  "updated_at": "2026-05-18T15:33:45Z"
}

​
レスポンスフィールド

フィールド型説明
file_idstringファイル ID（file_ プレフィックス）
filenamestring保存されたファイル名
size_bytesintegerファイルサイズ（バイト）
mime_typestringアップロード時に指定された MIME タイプ、またはファイル名から検出された MIME タイプ
purposestringファイル用途。ファイル用途を参照
statusstringファイル状態。ファイルステータスを参照
metadataJSON valueアップロード時に指定されたメタデータ JSON
created_atstring作成時刻（RFC 3339 形式の UTC）
updated_atstring更新時刻。created_at と異なる場合のみ返されます
session_idstringファイルが Session に関連付けられている場合に返されます

​
注意事項

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

​
エラーレスポンス

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

​
関連項目

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

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