Upload a file
⚠️
Preview — this feature is being built; the design below is the spec.
POST https://app.syntic.ai/v1/filesUpload 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
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <key>: a private inference key (sk_live_...). See Authentication. |
Body parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
file | file | Yes | The bytes, with a filename. |
purpose | string | Yes | document (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_days | integer | No | 1 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"
}| Field | Type | Description |
|---|---|---|
id | string | Starts with file_. Use it wherever a request accepts a file_id. |
object | string | Always file. |
filename | string | The name sent with the upload, or the name Syntic gave a generated file. |
purpose | string | document, vision, batch, code_input or skill. |
bytes | integer | Size in bytes. |
mime_type | string | Detected media type. |
created_at | integer | Unix seconds. |
expires_at | integer | Unix seconds when the file is deleted. Every file expires. |
status | string | processing (being scanned and prepared), ready, or failed with status_detail. |
source | string | upload, batch_output or code_execution. |
workspace_id | string | The 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.pdfErrors
Errors use the error envelope and carry a request_id. Codes specific to this operation:
| Status | type | code | When |
|---|---|---|---|
| 400 | invalid_request_error | invalid_purpose | Unknown purpose. |
| 400 | invalid_request_error | unsupported_file_type | The file type is not accepted for that purpose. |
| 400 | invalid_request_error | invalid_parameter | expires_after_days outside 1 to 90, or not 1 for a zero-data-retention organization. |
| 413 | invalid_request_error | file_too_large | Over 100 MB (500 MB for batch and code_input). |
| 507 | api_error | storage_quota_exceeded | Workspace storage (100 GB or 10,000 files) is full. |
| 401 | authentication_error | invalid_api_key | The key is missing, unknown, revoked or expired. |
| 429 | rate_limit_error | rate_limited | Too many requests; wait for Retry-After. See Rate-limit headers. |
Related
Was this page helpful?