Create upload API
View as Markdown · Open in Claude Desktop
Gets a place to put a file that is on the user's device or in your sandbox when there is no public URL. Returns a file_id to pass as source, an upload_page_url to show the user (they open it and drop the file; it resumes on weak connections), and an upload_put_url you can PUT the raw bytes to. The file_id works once the upload finishes. Unused uploads expire after 1 hour; uploaded files are deleted within 24 hours of the job that uses them.
- Endpoint
POST /v1/uploads- MCP name
create_upload- Available in MCP sets
- core, generate, full
What it draws
- Does not draw from the allowance.
Input
| Name | Type | Required | Description |
|---|---|---|---|
file_name | string | yes | File name with extension. |
size_bytes | integer | no | Size in bytes, if known. (at least 1) |
purpose | string | no | What the file is for. (one of "job_input", "library"; default "job_input") |
Output
| Name | Type | Required | Description |
|---|---|---|---|
file_id | string | yes | |
upload_id | string | no | |
upload_page_url | string or null | yes | Page where the user signs in and drops the file (it sends the file to this upload); null when the upload has no page. |
upload_put_url | string | no | |
expires_at | string | yes |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no | Required on POSTs that create a job, upload, checkout, plan change or top-up; stored 24 h per ledger subject; same key with a different body returns 409 IDEMPOTENCY_MISMATCH |
Examples
Set NEATTRIM_API_KEY to your key, then copy an example. A tool that draws from your allowance reads an uploaded file: upload a sample file as in the quickstart and set VIDEO_FILE_ID (or AUDIO_FILE_ID, IMAGE_FILE_ID, SUBTITLES_FILE_ID) to its file_id. Any other id in an example, such as JOB_ID, is read from a variable of the same name.
curl -X POST "https://api.neattrim.com/v1/uploads" \
-H "Authorization: Bearer $NEATTRIM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"file_name":"sample.mp4","size_bytes":301335,"mime_type":"video/mp4"}'Errors
400- BAD_REQUEST
401- UNAUTHENTICATED or INACTIVE
402- LIMIT (allowance used), NEEDS_PLAN (paid feature) or DECLINED
413- TOO_BIG or TOO_LONG for the caller's plan
415- UNSUPPORTED_MEDIA
429- RATE_LIMITED
Limits
- Largest upload
- Free: 200 MB, Plus: 2 GB, Pro: 4 GB
- Jobs running at once
- Free: 2, Plus: 3, Pro: 6
- Requests a minute
- Free: 60, Plus: 60, Pro: 60