Session リソースを追加

POST /api/v1/forward/sessions/{session_id}/resources 作成済み Session のサンドボックスランタイム環境にファイルリソースを追加でマウントします。セッションの進行中に一時的にファイルをアップロードする場合に使用します。ファイルは事前に Files API でアップロードする必要があります。このインターフェイスは type: "file" のみを受け付けます。

ファイルアップロードの要件

このエンドポイントで使用するファイルは、アップロード時に purpose=session_resource を明示することを推奨します。

curl -X POST 'https://api.qoder.com/api/v1/forward/files' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F 'file=@spec.md' \
  -F 'purpose=session_resource'

purpose を省略すると、Files API はデフォルトでファイルを user_upload として保存します。このファイルを Session に追加することはできますが、GET /api/v1/forward/files/{file_id}/content ではダウンロードできず、ダウンロード時に 403 permission_error が返されます。POST /api/v1/forward/sessions/{session_id}/resources は既存のファイルを Session にマウントするだけで、user_upload を session_resource に自動変換しません。後からダウンロードする必要がある場合は、ファイルのアップロード時に purpose=session_resource を指定してください。

ヘッダー

Header	必須	説明
Authorization	はい	`Bearer <PAT または SAT>`
Content-Type	はい	`application/json`

パスパラメーター

パラメーター	型	必須	説明
session_id	string	はい	Session ID。

リクエストボディ

パラメーター	型	必須	説明
type	string	はい	リソースタイプ。`file` である必要があります。
file_id	string	はい	Files API が返す File ID。ファイルのアップロードが完了している必要があります。
mount_path	string	いいえ	Agent コンテナ内のマウントパス。省略すると Forward がファイル名から生成します。デフォルトは `/data/workspace/<ファイル名>` です。

リクエスト例

curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/resources' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "file",
  "file_id": "file_019e6a18dc09abcd",
  "mount_path": "/data/workspace/spec.md"
}'

レスポンス例

HTTP 200 OK

{
  "id": "sesr_0e4323e8f47ba34853f5409e",
  "type": "file",
  "file_id": "file_019e6a18dc09abcd",
  "mount_path": "/data/workspace/spec.md",
  "created_at": "2026-06-23T05:53:19Z",
  "updated_at": "2026-06-23T05:53:38Z"
}

レスポンスフィールド

フィールド	型	説明
id	string	`sesr_` で始まる Session リソース ID。
type	string	リソースタイプ。常に `file`。
file_id	string	マウントされた File ID。
mount_path	string	Agent コンテナ内の実際のマウントパス。
created_at	string	RFC 3339 形式のリソース作成日時。
updated_at	string	RFC 3339 形式のリソース更新日時。

ファイルを Agent に通知

ファイルをマウントしても Agent は自動検出しません。Session Events を送信から user.message を送り、返されたファイルパスを含めます。

curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/events' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [{
    "type": "user.message",
    "content": [
      {"type": "text", "text": "ファイルを分析してください"},
      {"type": "text", "text": "ファイルパス：/data/workspace/spec.md"}
    ]
  }]
}'

メッセージには追加時に返された mount_path を使用します。

エラー

HTTP	Type	Code	発生条件
400	`invalid_request_error`	`invalid_request_body`	リクエストボディが有効な JSON ではありません。
400	`invalid_request_error`	`invalid_resource`	`type` が `file` ではない、`file_id` がない、またはフィールドに制御文字が含まれています。
404	`not_found_error`	`session_not_found`	Session が存在しません。
404	`not_found_error`	`file_not_found`	File が存在しないか、削除されています。
409	`conflict_error`	`session_archived`	Session がアーカイブされています。
409	`conflict_error`	`resource_conflict`	マウントパスが Session の既存リソースと競合しているか、ファイルがすでに現在の Session にマウントされています。
401	`authentication_error`	`authentication_required`	PAT または SAT が無効か、期限切れです。

注意事項

ファイルは事前に Files API で正常にアップロードする必要があります。マウント後、Agent はコンテナ内からファイルを読み取れますが、Event を送信してファイルパスを Agent に通知する必要があります。詳しくはファイルを Agent に通知を参照してください。
mount_path を省略すると、Forward は /data/workspace/<ファイル名> を生成します。同名ファイルが複数ある場合は、上書きを避けるため mount_path を明示してください。
このインターフェイスはファイルリソースの追加のみをサポートします。他のリソースタイプは受け付けません。
アーカイブ済み Session にはリソースを追加できません。続行するには新しい Session を作成してください。
追加したリソースは Session の取得および一覧レスポンスの resources に返され、リソースがない場合は空配列です。

​ファイルアップロードの要件

​ヘッダー

​パスパラメーター

​リクエストボディ

​リクエスト例

​レスポンス例

​レスポンスフィールド

​ファイルを Agent に通知

​エラー

​注意事項

​関連

Session を作成

ファイルをアップロード