> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ファイルのアップロード

> テキストベースのファイルをアップロードし、Session、ツール、Agent 出力で使用します。

`POST /api/v1/cloud/files`

テキストベースのファイルをアップロードし、[ファイルオブジェクト](/ja/cloud-agents/api/files/schemas#file-object)を返します。

## ヘッダー

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

## リクエストボディ

| フィールド      | 型           | 必須  | 説明                                                                                                       |
| ---------- | ----------- | --- | -------------------------------------------------------------------------------------------------------- |
| `file`     | file        | はい  | テキストベースのファイル内容。[サポートされるアップロードファイルタイプ](/ja/cloud-agents/api/files/schemas#supported-upload-file-types)を参照 |
| `name`     | string      | いいえ | 保存されるファイル名。デフォルトはアップロードされたファイル名。サーバーのサニタイズ後、長さは 1-255 バイトで `.` や `..` は不可                                |
| `metadata` | JSON string | いいえ | フォームフィールドとしてエンコードされた有効な JSON。最大生データ長は 8 KB。デフォルトは `{}`                                                   |

## リクエスト例

```bash theme={null}
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**

```json theme={null}
{
  "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"
}
```

## レスポンスフィールド

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

## 注意事項

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

## エラーレスポンス

| HTTP | type                    | 説明                                                                                     |
| ---- | ----------------------- | -------------------------------------------------------------------------------------- |
| 400  | `invalid_request_error` | `file` の欠落、無効なマルチパートフォーム、サポートされていないファイルタイプ、無効な `name`、無効な `metadata`、またはリクエストボディが大きすぎる |
| 401  | `authentication_error`  | 認証トークンが欠落または無効                                                                         |
| 500  | `api_error`             | ファイルストレージバックエンドが利用不可                                                                   |

[エラー](/ja/cloud-agents/api/conventions/errors)で完全なエラーエンベロープを参照してください。

## 関連項目

<CardGroup cols={2}>
  <Card title="ファイルの添付とダウンロード" icon="paperclip" href="/ja/cloud-agents/files">
    Agent にコンテキストを提供するファイルをアップロードし、Agent が生成したファイルをダウンロードします。
  </Card>
</CardGroup>