Skip to main content
Manage agent context

Files and Mounts

Upload files to give your agent context, and download files it produces.

The Files API lets you supply context to a Session — code repositories, configuration, reference docs, and so on. The Agent can read these files to understand the task.

Workflow

1

Upload file

POST /api/v1/cloud/files — upload text-based content.
2

Mount on Session

POST /api/v1/cloud/sessions/{session_id}/resources — attach the uploaded file to the Session.
3

Agent uses it

The Agent reads the file's contents during the Session and completes the task.

Upload a File

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

Parameters

FieldTypeRequiredDescription
filebinaryYesFile contents
namestringNoCustom filename
Use the File object's downloadable field to decide whether /content is available.

curl Upload Example

curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./src/main.py"
Response: 
{
  "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"
}
Uploading multiple files: 
# Upload one at a time
curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./config.yaml"

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

Mount on a Session

After uploading, use the Resources API to mount the file on a specific Session: 
POST https://api.qoder.com.cn/api/v1/cloud/sessions/{session_id}/resources
Request body — send a single file resource: 
{
  "type": "file",
  "file_id": "file_abc123",
  "mount_path": "/data/input.txt"
}

curl Mount Example

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions/sess_abc123/resources \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "file_id": "file_abc123",
    "mount_path": "/data/input.txt"
  }'
To attach multiple files after Session creation, call the endpoint once per file.

Download a File

Files with "downloadable": true can be downloaded: 
curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -o output.txt
For non-downloadable files, requests to /content return 403 Forbidden.

Inspect File Metadata

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

List Files

curl "https://api.qoder.com.cn/api/v1/cloud/files?scope_id=sess_abc123" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
Filtering by scope_id is supported for Session-scoped files.

Delivering and retrieving session outputs

A file the Agent generates in a Session reaches the client in these steps:
  1. The Agent writes the file under /data/ in the sandbox with Write
  2. The Agent calls DeliverArtifacts to deliver it as a File
  3. The event stream emits agent.artifact_delivered with file_id, original_filename, size, and content_type
  4. The client retrieves the file through the Files API
# List the Session's files (scope_id is the Session ID)
curl "https://api.qoder.com.cn/api/v1/cloud/files?scope_id=sess_abc123" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

# Get a temporary download URL, then request that URL to download the content
curl "https://api.qoder.com.cn/api/v1/cloud/files/file_abc123/content" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
For the endpoints, see List files and Download file content.
  • Only files with downloadable set to true can be downloaded.
  • A file can take a few seconds after delivery to appear in the list.
  • The Agent may also return the result directly in its reply. Clients should handle both cases.
  • To evaluate outputs against acceptance criteria, see Outcome Evaluation.

End-to-End Example

# 1. Upload the source file
FILE_ID=$(curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./app.py" | jq -r '.id')

echo "Uploaded: $FILE_ID"

# 2. Create a Session
SESSION_ID=$(curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agent_abc123", "environment_id": "env_abc123"}' | jq -r '.id')

# 3. Mount the file on the Session
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"type\": \"file\", \"file_id\": \"$FILE_ID\"}"

# 4. Send a task — the Agent can reference mounted files
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "Review app.py and fix the bugs."}]}
    ]
  }'

FAQ

Q: How long are uploaded files retained? A: Files are retained until you explicitly delete them via DELETE /api/v1/cloud/files/{file_id}. A file that is still referenced by an active Session cannot be deleted — remove or detach the Session first. Q: Can I attach files when creating a Session? A: Yes. Pass file resources in the resources field when creating the Session. See Sessions — Attach Resources at Creation. Q: Why can't I download some files? A: For security, some files are only available for the Agent's internal use. To export results, use files whose File object returns "downloadable": true. Q: Which file formats are supported? A: The upload API accepts text-based files. Code, configuration, and plain-text reference documents work best.