Attach and download files

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/api/v1/cloud/files
Content-Type: multipart/form-data

Parameters

Field	Type	Required	Description
file	binary	Yes	File contents
name	string	No	Custom filename

Use the File object’s downloadable field to decide whether /content is available.

Single file

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

curl Upload Example

curl -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -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/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"

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

Multiple files

# Upload one at a time
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"

Mount on a session

After uploading, use the Resources API to mount the file on a specific Session:

POST https://api.qoder.com/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"
}

Single file

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

Multiple files

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

Managing files

Get file metadata

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

To attach multiple files after Session creation, call the endpoint once per file.

Filtering by scope_id is supported for Session-scoped files.

Download a file

Files with "downloadable": true can be downloaded:

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

For non-downloadable files, requests to /content return 403 Forbidden.

End-to-end example

# 1. Upload the source file
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. Create a 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. Mount the file on the 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. Send a task — the Agent can reference mounted files
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."}]}
    ]
  }'

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.

Next steps

Start a session

Attach files at session creation time.

Build persistent memory

Persist Agent knowledge across Sessions.

Files API

The full Files API surface.