API referenceFilesUpload a file

Upload a file

⚠️
Preview — this feature is being built; the design below is the spec.
POST https://app.syntic.ai/v1/files

Upload a file once and reuse its id in chat requests, batches, code execution and skills. The request is multipart/form-data, not JSON. The file starts in processing while it is scanned and prepared, then becomes ready.

For how this fits into a full workflow, see Files API.

Headers

HeaderRequiredValue
AuthorizationYesBearer <key>: a private inference key (sk_live_...). See Authentication.

Body parameters

ParameterTypeRequiredNotes
filefileYesThe bytes, with a filename.
purposestringYesdocument (PDF, DOCX, PPTX, XLSX, CSV, TXT, MD, HTML, JSON), vision (PNG, JPEG, WebP, GIF), batch (JSONL), code_input (any type) or skill (ZIP).
expires_after_daysintegerNo1 to 90. Default 30. Organizations with zero data retention must send 1.

Send the fields as multipart form parts. The Content-Type header is set by your HTTP client, including the boundary; do not set it by hand.

Response

201 Created, Content-Type: application/json

{
  "id": "file_01JBW9Q6RZ",
  "object": "file",
  "filename": "lease.pdf",
  "purpose": "document",
  "bytes": 482113,
  "mime_type": "application/pdf",
  "created_at": 1791820800,
  "expires_at": 1792425600,
  "status": "processing",
  "source": "upload",
  "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q"
}
FieldTypeDescription
idstringStarts with file_. Use it wherever a request accepts a file_id.
objectstringAlways file.
filenamestringThe name sent with the upload, or the name Syntic gave a generated file.
purposestringdocument, vision, batch, code_input or skill.
bytesintegerSize in bytes.
mime_typestringDetected media type.
created_atintegerUnix seconds.
expires_atintegerUnix seconds when the file is deleted. Every file expires.
statusstringprocessing (being scanned and prepared), ready, or failed with status_detail.
sourcestringupload, batch_output or code_execution.
workspace_idstringThe workspace that owns the file.

Examples

curl -sS https://app.syntic.ai/v1/files \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -F purpose=document \
  -F expires_after_days=7 \
  -F file=@lease.pdf

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
400invalid_request_errorinvalid_purposeUnknown purpose.
400invalid_request_errorunsupported_file_typeThe file type is not accepted for that purpose.
400invalid_request_errorinvalid_parameterexpires_after_days outside 1 to 90, or not 1 for a zero-data-retention organization.
413invalid_request_errorfile_too_largeOver 100 MB (500 MB for batch and code_input).
507api_errorstorage_quota_exceededWorkspace storage (100 GB or 10,000 files) is full.
401authentication_errorinvalid_api_keyThe key is missing, unknown, revoked or expired.
429rate_limit_errorrate_limitedToo many requests; wait for Retry-After. See Rate-limit headers.
Was this page helpful?