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.
POST /v1/files
Uploads a file to the Qoder Cloud Agents platform for use in sessions or tools.
Content-Type: multipart/form-data
| Header | Required | Description |
|---|
Authorization | Yes | Bearer $QODER_PAT |
Request body (multipart/form-data)
| Field | Type | Required | Description |
|---|
file | file | Yes | Binary contents of the file to upload |
purpose | string | No | File purpose. One of: user_upload, tool_output, skill_output, session_resource, agent_output. Defaults to user_upload |
metadata | JSON string | No | Custom metadata as a JSON object |
Example request
curl -X POST "https://openapi.qoder.sh/api/v1/cloud/files" \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@./my-document.txt" \
-F "purpose=session_resource" \
-F 'metadata={"project":"demo"}'
Example response
HTTP 201 Created
{
"created_at": "2026-05-18T15:33:44Z",
"file_id": "file_019e3bb8c1387743bf4ef115aae5acb1",
"filename": "my-document.txt",
"metadata": {
"project": "demo"
},
"mime_type": "text/plain",
"purpose": "session_resource",
"size_bytes": 110,
"status": "ready",
"updated_at": "2026-05-18T15:33:44Z"
}
Response fields
| Field | Type | Description |
|---|
file_id | string | File unique identifier with the file_ prefix |
filename | string | Original filename |
size_bytes | integer | File size in bytes |
mime_type | string | MIME type, auto-detected by the server |
purpose | string | File purpose |
status | string | File status; ready after a successful upload |
metadata | object | Custom metadata |
created_at | string | Creation time (ISO 8601) |
updated_at | string | Last update time (ISO 8601) |
Errors
| HTTP | Type | Trigger |
|---|
| 400 | invalid_request_error | Missing file field or invalid purpose value |
| 401 | – | Missing or invalid authentication token |
Error response examples
{
"error": {
"message": "Field 'file' is required.",
"type": "invalid_request_error"
},
"type": "error"
}
{
"error": {
"message": "Field 'purpose' must be one of: user_upload, tool_output, skill_output, session_resource, agent_output.",
"type": "invalid_request_error"
},
"type": "error"
}
