Skip to main content
POST /v1/files Uploads a file to the Qoder Cloud Agents platform for use in sessions or tools. Content-Type: multipart/form-data

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer $QODER_PAT

​
Request body (multipart/form-data)

FieldTypeRequiredDescription
filefileYesBinary contents of the file to upload
purposestringNoFile purpose. Value: user_upload. Defaults to user_upload
metadataJSON stringNoCustom metadata as a JSON object

​
Example request

curl -X POST "https://api.qoder.com/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./my-document.txt" \
  -F "purpose=user_upload" \
  -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": "user_upload",
  "size_bytes": 110,
  "status": "ready",
  "updated_at": "2026-05-18T15:33:44Z"
}

​
Response fields

FieldTypeDescription
file_idstringFile unique identifier with the file_ prefix
filenamestringOriginal filename
size_bytesintegerFile size in bytes
mime_typestringMIME type, auto-detected by the server
purposestringFile purpose
statusstringFile status; ready after a successful upload
metadataobjectCustom metadata
created_atstringCreation time (ISO 8601)
updated_atstringLast update time (ISO 8601)

​
Errors

HTTPTypeTrigger
400invalid_request_errorMissing 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.",
    "type": "invalid_request_error"
  },
  "type": "error"
}
See Errors for the full error envelope.