> ## 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.
# ファイルの添付とダウンロード
> Agent にコンテキストを与えるファイルをアップロードし、Agent が生成したファイルをダウンロードします。
ファイル API を使うと、Session にコンテキスト — コードリポジトリ、構成、参考ドキュメントなど — を提供できます。Agent はこれらのファイルを読み取ってタスクを理解します。
## 基本フロー
`POST /api/v1/cloud/files` — テキストベースの内容をアップロードします。
`POST /api/v1/cloud/sessions/{session_id}/resources` — アップロード済みファイルを Session にアタッチします。
Session 中に Agent がファイル内容を読み取り、タスクを完了します。
## ファイルをアップロードする
```
POST https://api.qoder.com/api/v1/cloud/files
Content-Type: multipart/form-data
```
### パラメータ
| フィールド | 型 | 必須 | 説明 |
| ------ | ------ | --- | --------- |
| `file` | binary | はい | ファイル内容 |
| `name` | string | いいえ | カスタムファイル名 |
`/content` が利用可能かどうかは、ファイルオブジェクトの `downloadable` フィールドで判断してください。
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/files \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./src/main.py"
```
## curl アップロード例
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/files \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./src/main.py"
```
レスポンス:
```json theme={null}
{
"id": "file_019e6a18dc0978e9a2104c9b269748ac",
"type": "file",
"filename": "main.py",
"size_bytes": 4096,
"downloadable": false,
"mime_type": "text/plain",
"scope": null,
"created_at": "2026-05-01T10:00:00Z"
}
```
複数ファイルのアップロード:
```bash theme={null}
# 1 つずつアップロード
curl -X POST https://api.qoder.com/api/v1/cloud/files \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./config.yaml"
curl -X POST https://api.qoder.com/api/v1/cloud/files \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./requirements.txt"
```
```json theme={null}
{
"id": "file_019e6a18dc0978e9a2104c9b269748ac",
"type": "file",
"filename": "main.py",
"size_bytes": 4096,
"downloadable": false,
"mime_type": "text/plain",
"scope": null,
"created_at": "2026-05-01T10:00:00Z"
}
```
```bash theme={null}
# 1 つずつアップロード
curl -X POST https://api.qoder.com/api/v1/cloud/files \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./config.yaml"
curl -X POST https://api.qoder.com/api/v1/cloud/files \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./requirements.txt"
```
## Session にマウントする
アップロード後、Resources API でファイルを特定の Session にマウントします。
```
POST https://api.qoder.com/api/v1/cloud/sessions/{session_id}/resources
```
リクエストボディ — 単一のファイルリソースを送信:
```json theme={null}
{
"type": "file",
"file_id": "file_abc123",
"mount_path": "/data/input.txt"
}
```
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"resources": [
{"type": "file", "file_id": "file_abc123"}
]
}'
```
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"resources": [
{"type": "file", "file_id": "file_abc123"},
{"type": "file", "file_id": "file_def456"},
{"type": "file", "file_id": "file_ghi789"}
]
}'
```
## ファイルを管理する
### ファイルメタデータを取得
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"type": "file",
"file_id": "file_abc123",
"mount_path": "/data/input.txt"
}'
```
Session 作成後に複数のファイルをアタッチするには、ファイルごとにこのエンドポイントを 1 回ずつ呼び出します。
Session スコープのファイルでは `scope_id` でのフィルタリングがサポートされます。
### ファイルをダウンロード
`"downloadable": true` のファイルはダウンロードできます。
```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/files/file_abc123/content \
-H "Authorization: Bearer $QODER_PAT" \
-o output.txt
```
ダウンロード不可のファイルでは、`/content` へのリクエストは `403 Forbidden` を返します。
## エンドツーエンドの例
```bash theme={null}
# 1. ソースファイルをアップロード
FILE_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/files \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./app.py" | jq -r '.id')
echo "Uploaded: $FILE_ID"
# 2. Session を作成
SESSION_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{"agent": "agent_abc123", "environment_id": "env_abc123"}' | jq -r '.id')
# 3. ファイルを Session にマウント
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/resources" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d "{\"type\": \"file\", \"file_id\": \"$FILE_ID\"}"
# 4. タスクを送信 — Agent はマウント済みファイルを参照できる
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"events": [
{"type": "user.message", "content": [{"type": "text", "text": "Review app.py and fix the bugs."}]}
]
}'
```
## よくある質問
**Q: アップロードしたファイルはどれくらい保持されますか?**
A: ファイルは `DELETE /api/v1/cloud/files/{file_id}` で明示的に削除するまで保持されます。アクティブな Session からまだ参照されているファイルは削除できません。先に該当する Session を削除するかデタッチしてください。
**Q: Session 作成時にファイルを添付できますか?**
A: はい。Session 作成時に `resources` フィールドでファイルリソースを渡します。[Sessions — 作成時にリソースをアタッチ](/ja/cloud-agents/sessions#attach-resources-at-creation) を参照してください。
**Q: なぜ一部のファイルはダウンロードできないのですか?**
A: セキュリティ上、一部のファイルは Agent の内部利用のみとしています。結果をエクスポートするには、ファイルオブジェクトが `"downloadable": true` を返すファイルを使用してください。
**Q: どのファイル形式がサポートされますか?**
A: アップロード API はテキストベースのファイルを受け付けます。コード、構成、プレーンテキストの参考ドキュメントが最も適しています。
## 次のステップ
Session 作成時にファイルを添付する。
Session 間で Agent の知識を永続化する。
完全な Files API。