# Files

URL: https://neattrim.com/docs/files

Upload files, pass URLs, and download outputs from the Neattrim API.

A tool reads its input from the `source` field. It takes an `https://` URL that returns the file directly, or a `file_id` from an upload or from an earlier job. A tool that draws from your allowance needs a `file_id`: the API measures an uploaded file before it reserves time, and refuses a URL with `400 BAD_REQUEST` and the fix "Upload the file with create_upload and pass its file_id." A tool that draws nothing, such as `probe_media` or `convert_subtitles`, takes either. An address on neattrim.com itself is not accepted as a source: upload the file instead.

## Upload a file

1. `POST /v1/uploads` with the file name, size and type. The answer says whether to send one presigned `PUT` or several parts.
2. Send the bytes. For a multipart upload, `PUT /v1/uploads/<id>/parts/<n>` for each part. `GET /v1/uploads/<id>` lists the parts the server already has, so an interrupted upload can resume.
3. `POST /v1/uploads/<id>/complete`. The `file_id` is in the answer of step 1 and can be used once this call succeeds. The [quickstart](https://neattrim.com/docs/quickstart#3-upload-a-sample-file) shows the three calls with curl.

The SDKs do these steps for you with `upload()`. Your plan sets the largest file you can upload: 200 MB on Free, 2 GB on Plus and 4 GB on Pro. A file above the limit gets `413 TOO_BIG`.

## URLs we refuse

We fetch a URL only when it returns the media file itself. We refuse links to video-platform pages, private network addresses and anything that redirects to one. The answer is `422 SOURCE_REFUSED` with the reason.

## Outputs and expiry

A finished job lists output files. `GET /v1/files/<id>` returns the file details and a fresh signed link. Download links made through the API stay valid for 24 hours; ask again for a new one.

Results are kept for 7 days. Your library holds up to 1 GB on Free and 5 GB on paid plans. When the library is full, the oldest items are deleted. Set `keep` to `false` on a job to delete its results after 24 hours. `DELETE /v1/files/<id>` removes a file at once.
