---
title: "Files API: upload PDFs and images for the Responses API"
description: "Upload PDFs, images and documents, then reference file_id values from the Responses API."
source: https://lazu.ai/docs/endpoints/files
updated: 2026-10-02
---

# Files API

**POST** `/v1/files`

Upload documents and images once, then reference them by file\_id from the Responses API. The file API is OpenAI-compatible where possible, with explicit Lazu retention and purpose rules.

## Example request

```bash
curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -F purpose=user_data \
  -F file=@./paper.pdf
```

## Example response

```json
{
  "id": "file-lazu-01ABCDEF",
  "object": "file",
  "bytes": 421337,
  "filename": "paper.pdf",
  "purpose": "user_data",
  "created_at": 1765980000
}
```

## File endpoints

| Method | Path                    | Purpose        |
| ------ | ----------------------- | -------------- |
| POST   | `/v1/files`             | Upload         |
| GET    | `/v1/files`             | List           |
| GET    | `/v1/files/:id`         | Metadata       |
| GET    | `/v1/files/:id/content` | Download bytes |
| DELETE | `/v1/files/:id`         | Delete         |

All endpoints use `Authorization: Bearer $LAZU_API_KEY`.

## Upload request

- `purpose` `string` (required) — Declares how the file can be used. One of: `user_data`, `vision`
- `file` `multipart file` (required) — Uploaded file bytes.

## Supported purposes

- **user\_data** — Up to 512 MB. Use for PDFs, text and structured data passed through
  Responses as `input_file`.
- **vision** — Up to 20 MB. Allowed mime types: `image/png`,
  `image/jpeg`, `image/gif`, `image/webp`.

OpenAI's `batch`, `fine-tune` and

`assistants` purposes are not yet supported. Executable file
extensions are rejected regardless of purpose.

## Upload response

- `id` `string` — File ID, for example `file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX`.
- `object` `string` — Always `file`.
- `bytes` `integer` — Uploaded byte size.
- `filename` `string` — Original filename.
- `purpose` `string` — Stored purpose.
- `status` `string` — Usually `processed`.

Lazu returns `201 Created` for successful uploads. Treat it as
success if your client SDK expects `200`.

## Reference from Responses

Lazu dereferences `file_id` only on
[Responses](https://lazu.ai/docs/endpoints/responses). Chat completions does not pull file content
automatically.

For images uploaded with `purpose=vision`, use

`input_image` instead of `input_file`.

## Limits

| Limit                                          | Value  |
| ---------------------------------------------- | ------ |
| Single file with `purpose=user_data`           | 512 MB |
| Single file with `purpose=vision`              | 20 MB  |
| Total bytes dereferenced in one Responses call | 64 MB  |

## Errors

- `missing_required_parameter` `400` — Missing `purpose` or file bytes.
- `purpose_not_supported` `400` — Unsupported purpose such as `batch` or `fine-tune`.
- `file_too_large` `413` — Single file or total dereferenced files exceed limits.
- `file_not_found` `404` — File does not exist or is not owned by the current API key.