Skip to main content
Manage Sessions

Files and Mounts

The Files API lets you attach files — code repositories, configuration, reference docs — to a Session for the Agent to read during task execution.

Workflow

  1. Upload filePOST /files — upload the binary content and choose a purpose.
  2. Mount on SessionPOST /sessions/{session_id}/resources — attach the uploaded file to the Session.
  3. Agent uses itThe 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
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.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./src/main.py" \
  -F "purpose=user_upload"
Response: 
{
  "file_id": "file_019e6a18dc0978e9a2104c9b269748ac",
  "filename": "main.py",
  "purpose": "user_upload",
  "size_bytes": 4096,
  "metadata": {},
  "mime_type": "text/plain",
  "status": "ready",
  "created_at": "2026-05-01T10:00:00Z",
  "updated_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_PAT" \
  -F "file=@./config.yaml" \
  -F "purpose=user_upload"

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

Mount on a Session

After uploading, mount the file on a Session with the Resources API: 
POST https://api.qoder.com.cn/api/v1/cloud/sessions/{session_id}/resources
Request body — pass one or more entries in a resources array: 
{
  "resources": [
    {
      "type": "file",
      "file_id": "file_abc123"
    }
  ]
}

curl Mount Example

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

List Files

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

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_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.cn/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.cn/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.cn/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 accessible only to the Agent internally. To export results, have the Agent produce files with tool_output or skill_output purpose. Q: Which file formats are supported? A: Any binary file is accepted. Text-based files (code, configuration, documents) yield the best results.
Guides
Tutorials
API Reference