Add a session resource

POST /api/v1/forward/sessions/{session_id}/resources Mounts an additional file resource in the sandbox runtime of an existing session. Use this endpoint when you need to upload a file while a session is in progress. The file must first be uploaded through the Files API. This endpoint accepts only type: "file".

File upload requirements

For files used with this endpoint, specify purpose=session_resource when uploading:

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'

If you omit purpose, the Files API stores the file as user_upload by default. The file can still be added to a session, but it cannot be downloaded through GET /api/v1/forward/files/{file_id}/content; attempting to download it returns 403 permission_error. POST /api/v1/forward/sessions/{session_id}/resources only mounts the existing file in the session and does not convert user_upload to session_resource. To download the file later, you must specify purpose=session_resource when uploading it.

Headers

Header	Required	Description
Authorization	Yes	`Bearer <PAT or SAT>`
Content-Type	Yes	`application/json`

Path parameters

Parameter	Type	Required	Description
session_id	string	Yes	Session ID.

Request body

Parameter	Type	Required	Description
type	string	Yes	Resource type. Must be `file`.
file_id	string	Yes	File ID returned by the Files API. The file must have finished uploading.
mount_path	string	No	Mount path in the Agent container. If omitted, Forward generates a path from the file name. The default is `/data/workspace/<file-name>`.

Example request

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"
}'

Example response

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"
}

Response fields

Field	Type	Description
id	string	Session resource ID, prefixed with `sesr_`.
type	string	Resource type. Always `file`.
file_id	string	Mounted File ID.
mount_path	string	Actual mount path in the Agent container.
created_at	string	Resource creation time in RFC 3339 format.
updated_at	string	Resource update time in RFC 3339 format.

Notify the Agent about the file

After mounting the file, the Agent does not detect it automatically. Send a user.message through Send session events and include the returned file path:

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": "Analyze the file"},
      {"type": "text", "text": "File path: /data/workspace/spec.md"}
    ]
  }]
}'

Use the mount_path returned when the resource was added.

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_request_body`	The request body is not valid JSON.
400	`invalid_request_error`	`invalid_resource`	`type` is not `file`, `file_id` is missing, or a field contains control characters.
404	`not_found_error`	`session_not_found`	The session does not exist.
404	`not_found_error`	`file_not_found`	The file does not exist or has been deleted.
409	`conflict_error`	`session_archived`	The session is archived.
409	`conflict_error`	`resource_conflict`	The mount path conflicts with an existing session resource, or the file is already mounted in the session.
401	`authentication_error`	`authentication_required`	The PAT or SAT is invalid or expired.

Notes

The file must first be uploaded successfully through the Files API. After it is mounted, the Agent can read it from the container, but you must still send an Event to tell the Agent the file path; see Notify the Agent about the file.
If mount_path is omitted, Forward generates /data/workspace/<file-name>. Explicitly specify mount_path when mounting files with the same name to avoid overwriting.
This endpoint supports only adding file resources. Other resource types are rejected.
You cannot add resources to an archived session. Create a new session to continue.
Added resources are returned in the resources field of the get-session and list-sessions responses; the value is an empty array when no resources are mounted.

Add a session resource

File upload requirements

Headers

Path parameters

Request body

Example request

Example response

Response fields

Notify the Agent about the file

Errors

Notes

Create a session

Upload a file

​File upload requirements

​Headers

​Path parameters

​Request body

​Example request

​Example response

​Response fields

​Notify the Agent about the file

​Errors

​Notes

​Related

Create a session

Upload a file

File upload requirements

Headers

Path parameters

Request body

Example request

Example response

Response fields

Notify the Agent about the file

Errors

Notes

Related