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
Upload file
POST /files — upload the binary content and choose a purpose.
Mount on Session
POST /sessions/{session_id}/resources — attach the uploaded file to the Session.
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 filebinary Yes File contents purposestring Yes File purpose (see table) filenamestring No Custom filename
Purpose values Value Meaning Producer Downloadable user_uploadUser-uploaded input file User No tool_outputFile produced by a tool execution Agent/tool Yes skill_outputFile produced by a Skill Agent/Skill Yes session_resourceSession-scoped resource file User/system No agent_outputFinal Agent output file Agent No
Only tool_output and skill_output files are downloadable via the /content endpoint. Other purposes are for internal Agent use only.
Single file
Multiple files
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_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" }
# 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" } ] }
Single file
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"} ] }'
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 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.
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.
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: Yes. Pass file resources in the resources field when creating the Session. See Sessions — Attach Resources at Creation .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.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.
