# Upload a file

`POST https://api.parasend.com/v1/files`

Source: https://parasend.com/docs/api/files/upload

Authentication: `Authorization: Bearer <API key>` (a `ps_test_` key in test mode, `ps_live_` in live mode).
Send an `Idempotency-Key` header: a retry with the same key returns the first answer.

Uploads a file to send, as `multipart/form-data` with one `file` part, up to 32 MB. The file can be used in a delivery as soon as the upload completes and its SHA-256 is recorded.

## Body (multipart/form-data)

- `file` (string · binary, optional)

## Example: Upload a PDF

```bash
curl -X POST "https://api.parasend.com/v1/files" \
  -H "Authorization: Bearer $PARASEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@test-notice.pdf"
```

```js
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', new Blob([await readFile('test-notice.pdf')], { type: 'application/pdf' }), 'test-notice.pdf');

const res = await fetch('https://api.parasend.com/v1/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PARASEND_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: form,
});
const data = await res.json();
```

## Response 201

Uploaded.

```json
{
  "id": "fil_01M6R27SZK99V6N6WG4GK15T6R",
  "object": "file",
  "name": "test-notice.pdf",
  "bytes": 691,
  "sha256": "1b0cff41d97c8dcf92b7de986d66d12fb94e68f6db19821aa4b263dcfb0b6225",
  "created": "2026-11-06T09:15:05.587Z"
}
```

Errors: one shape, `{"error": {type, code, message, param, request_id}}`; every code is listed at https://parasend.com/docs/errors.