# Create upload API

URL: https://neattrim.com/docs/tools/create_upload

Gets a place to put a file that is on the user's device or in your sandbox when there is no public URL.

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 |  |

Endpoint: `POST /v1/uploads`

Who can call it: An API key, or an OAuth token for an app.

## 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 |

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file_name` | string | yes |  |
| `size_bytes` | integer | yes |  (at least 1) |
| `mime_type` | string | yes |  |
| `sha256` | string | no |  |
| `purpose` | any | no |  (one of "job_input", "library"; default "job_input") |
| `part_size` | integer | no |  (one of 5242880, 8388608; default 8388608) |
| `multipart` | boolean | no | API/MCP only: use presigned multipart; GET each part URL. Web always uses the proxy. (default false) |

## 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

```bash
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"}'
```

### TypeScript

```ts
// @neattrim/sdk is not on npm yet: it arrives with the first client release. Use the curl example today.
import { api, Neattrim, unwrap } from "@neattrim/sdk";

const client = new Neattrim({ apiKey: process.env.NEATTRIM_API_KEY });
const result = unwrap(
  await api.createUpload({
    client: client.client,
    body: {
      "file_name": "sample.mp4",
      "size_bytes": 301335,
      "mime_type": "video/mp4"
    },
  }),
);
console.log(result);
```

### Python

```python
# neattrim is not on PyPI yet: it arrives with the first client release. Use the curl example today.
import os

from neattrim import Neattrim
from neattrim_generated.api.uploads import create_upload
from neattrim_generated.models import CreateUploadBody

with Neattrim(api_key=os.environ["NEATTRIM_API_KEY"], base_url="https://api.neattrim.com") as client:
    result = create_upload.sync(client=client.client, body=CreateUploadBody.from_dict({"file_name": "sample.mp4", "size_bytes": 301335, "mime_type": "video/mp4"}))
    print(result)
```

## Response 201

Upload

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `upload_id` | string | yes |  |
| `file_id` | string | yes |  |
| `mode` | any | yes |  (one of "proxy", "presigned") |
| `part_size` | integer | no | Fixed when the upload is created; only concurrency adapts |
| `part_count` | integer | no |  |
| `parts_done` | array of integer | no |  |
| `put_url` | string or null | no |  |
| `upload_page_url` | string or null | no |  |
| `expires_at` | string | yes |  |

## 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
