Skip to main content
POST /api/v1/cloud/files Uploads a text-based file and returns a File object.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer $QODER_PAT
Content-TypeYesmultipart/form-data

​
Request body

FieldTypeRequiredDescription
filefileYesText-based file content. See Supported upload file types
namestringNoStored file name. Defaults to the uploaded file name. After server sanitization, length must be 1-255 bytes and cannot be . or ..
metadataJSON stringNoValid JSON encoded as a form field. Maximum raw length is 8 KB. Defaults to {}

​
Example request

curl -X POST "https://api.qoder.com/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./my-document.txt" \
  -F "name=my-document.txt" \
  -F 'metadata={"project":"demo"}'

​
Example response

HTTP 200 OK 
{
  "id": "file_019e3bb8c1387743bf4ef115aae5acb1",
  "type": "file",
  "filename": "my-document.txt",
  "mime_type": "text/plain",
  "size_bytes": 110,
  "downloadable": false,
  "scope": null,
  "metadata": {
    "project": "demo"
  },
  "created_at": "2026-05-18T15:33:44Z"
}

​
Response fields

FieldTypeDescription
idstringFile ID with the file_ prefix
typestringAlways "file"
filenamestringStored file name
size_bytesintegerFile size in bytes
mime_typestringMIME type supplied by the upload or detected from the file name
downloadablebooleanWhether this file can be downloaded through the /content endpoint
scopeobject | nullScope object when the file is associated with another resource, for example { "id": "sess_...", "type": "session" }
metadataobjectCustom metadata object supplied on upload; defaults to {}
created_atstringUTC creation time in RFC 3339 format

​
Notes

  • The multipart request body is limited to about 5 MB of file content plus multipart overhead.
  • Only text-based files are accepted. Binary document, image, audio, video, and archive files are rejected.
  • The server sanitizes name by keeping the base file name and replacing path separators or null bytes with _.

​
Errors

HTTPTypeTrigger
400invalid_request_errorMissing file, invalid multipart form, unsupported file type, invalid name, invalid metadata, or request body too large
401authentication_errorMissing or invalid authentication token
500api_errorFile storage backend is unavailable
See Errors for the full error envelope.

Attach and download files

Upload files to give your agent context, and download files it produces.