Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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 /files — upload the binary content and choose a purpose.
2

Mount on Session

POST /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

FieldTypeRequiredDescription
filebinaryYesFile contents
purposestringYesFile purpose (see table)
filenamestringNoCustom filename

​
Purpose Values

ValueMeaningProducerDownloadable
user_uploadUser-uploaded input fileUserNo
tool_outputFile produced by a tool executionAgent/toolYes
skill_outputFile produced by a SkillAgent/SkillYes
session_resourceSession-scoped resource fileUser/systemNo
agent_outputFinal Agent output fileAgentNo
Only tool_output and skill_output files are downloadable via the /content endpoint. Other purposes are for internal Agent use only.

​
curl Upload Example

curl -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./src/main.py" \
  -F "purpose=user_upload"
Response: 
{
  "file_id": "file_abc123",
  "filename": "main.py",
  "purpose": "user_upload",
  "size_bytes": 4096,
  "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" \
  -F "purpose=user_upload"

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

​
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 — wrap entries in a resources array, which also supports batched mounts: 
{
  "resources": [
    {
      "type": "file",
      "file_id": "file_abc123"
    }
  ]
}

​
curl Mount Example

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"}
    ]
  }'
Mounting multiple files in a single request: 
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"}
    ]
  }'

​
Download a File

Only tool_output and skill_output files can be downloaded: 
curl https://api.qoder.com/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_PAT" \
  -o output.txt
For other purposes, requests to /content return 403 Forbidden.

​
Inspect File Metadata

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

​
List Files

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

​
Size Limits

LimitValue
Per file50 MB
Total mounted on a single Session500 MB
Upload request timeout120 seconds

​
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" \
  -F "purpose=user_upload" | jq -r '.file_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"}' | 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 "{\"resources\": [{\"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 share the lifecycle of the parent resource (Agent or Session). When the Session is deleted, related files are cleaned up. Q: Can I attach files when creating a Session? A: Today this requires two steps: upload, then mount. A combined operation may be added later. Q: Why can’t I download user_upload files? A: For security, raw user uploads are only available for the Agent’s internal use. To export results, the Agent should produce new files with tool_output or skill_output purposes. Q: Which file formats are supported? A: Any binary file is allowed. Text-like files (code, configuration, documents) yield the best comprehension.