Qoder CN シリーズ:ファイルとマウント

ワークフロー

POST /files — バイナリコンテンツをアップロードし、purpose を選択します。

POST /sessions/{session_id}/resources — アップロードしたファイルをセッションにアタッチします。

エージェントはセッション中にファイルの内容を読み取り、タスクを完了します。

ファイルのアップロード

POST https://api.qoder.com.cn/api/v1/cloud/files
Content-Type: multipart/form-data

パラメータ

フィールド	タイプ	必須	説明
file	バイナリ	はい	ファイルの内容
purpose	文字列	はい	ファイルの用途 (下表を参照)
filename	文字列	いいえ	カスタムファイル名

purpose の値

値	意味	生成元	ダウンロード可否
user_upload	ユーザーがアップロードした入力ファイル	ユーザー	いいえ
tool_output	ツール実行によって生成されたファイル	エージェント / ツール	はい
skill_output	スキルによって生成されたファイル	エージェント / スキル	はい
session_resource	セッションスコープのリソースファイル	ユーザー / システム	いいえ
agent_output	エージェントの最終出力ファイル	エージェント	いいえ

tool_output と skill_output のファイルのみが /content エンドポイント経由でダウンロードできます。その他の用途のファイルは、エージェントの内部使用専用です。

curl によるアップロード例

curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./src/main.py" \
  -F "purpose=user_upload"

レスポンス：

{
  "file_id": "file_019e6a18dc0978e9a2104c9b269748ac",
  "filename": "main.py",
  "purpose": "user_upload",
  "size_bytes": 4096,
  "metadata": {},
  "mime_type": "text/plain",
  "status": "ready",
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}

複数のファイルをアップロードする場合：

# 1 つずつアップロード
curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./config.yaml" \
  -F "purpose=user_upload"

curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./requirements.txt" \
  -F "purpose=user_upload"

セッションへのマウント

アップロード後、Resources API を使用して、ファイルを特定のセッションにマウントします。

POST https://api.qoder.com.cn/api/v1/cloud/sessions/{session_id}/resources

リクエストボディ — エントリを resources 配列でラップします。これにより、バッチマウントも可能です。

{
  "resources": [
    {
      "type": "file",
      "file_id": "file_abc123"
    }
  ]
}

curl によるマウント例

curl -X POST https://api.qoder.com.cn/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"}
    ]
  }'

1 つのリクエストで複数のファイルをマウントする場合：

curl -X POST https://api.qoder.com.cn/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"}
    ]
  }'

ファイルのダウンロード

tool_output と skill_output のファイルのみダウンロードできます。

curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_PAT" \
  -o output.txt

その他の用途の場合、/content へのリクエストは 403 Forbidden を返します。

ファイルメタデータの確認

curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123 \
  -H "Authorization: Bearer $QODER_PAT"

ファイルの一覧表示

curl "https://api.qoder.com.cn/api/v1/cloud/files?purpose=user_upload" \
  -H "Authorization: Bearer $QODER_PAT"

purpose によるフィルタリングが可能です。

エンドツーエンドの例

# 1. ソースファイルをアップロード
FILE_ID=$(curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./app.py" \
  -F "purpose=user_upload" | jq -r '.file_id')

echo "Uploaded: $FILE_ID"

# 2. セッションを作成
SESSION_ID=$(curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agent_abc123"}' | jq -r '.id')

# 3. ファイルをセッションにマウント
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{\"resources\": [{\"type\": \"file\", \"file_id\": \"$FILE_ID\"}]}"

# 4. タスクを送信 — エージェントはマウントされたファイルを参照できます
curl -X POST "https://api.qoder.com.cn/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： ファイルは親リソース (エージェントまたはセッション) のライフサイクルを共有します。セッションが削除されると、関連するファイルもクリーンアップされます。

Q： セッションの作成時にファイルをアタッチできますか? A： 現時点では、アップロードとマウントの 2 つのステップが必要です。統合された操作は後日追加される可能性があります。

Q： user_upload ファイルをダウンロードできないのはなぜですか? A： セキュリティ上の理由から、ユーザーがアップロードした生のファイルは、エージェントの内部使用専用です。結果をエクスポートするには、エージェントが tool_output または skill_output の用途で新しいファイルを生成する必要があります。

Q： どのファイル形式がサポートされていますか? A： 任意のバイナリファイルを使用できます。テキストベースのファイル (コード、設定、ドキュメント) が最も理解しやすい形式です。