> Revox API docs for developers and AI agents. Index: https://www.getrevox.com/docs/api/llms.txt · Everything in one file: https://www.getrevox.com/docs/api/llms-full.txt · OpenAPI 3.1: https://www.getrevox.com/openapi.json · MCP server: https://www.getrevox.com/mcp
> Base URL https://www.getrevox.com/api · Auth: `Authorization: Bearer $REVOX_API_KEY`

# Upload a file to the knowledge base

`POST https://www.getrevox.com/api/assistants/{id}/knowledge/uploads`

A PDF or an image. Returns the document and a link to upload the file to.

## Before you call

- Then PUT the file's bytes to `upload_url` within 5 minutes, with the same Content-Type and Content-Length.
- The text is read by OCR once the file lands: poll [`GET /assistants/{id}/knowledge/{documentId}`](https://www.getrevox.com/docs/api/assistants/get-a-knowledge-document.md) until `status` is `ready` (`failed` if the file never came).

## Request

```bash
curl -X POST "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/knowledge/uploads" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Biens en vente",
    "content_type": "application/pdf",
    "size_bytes": 1
  }'
```

## Path parameters

- `id` (string, required): ID of the assistant, as returned by [`GET /assistants`](https://www.getrevox.com/docs/api/assistants/get-assistants.md).

## Body

JSON.

- `title` (string, required): Name of the document, unique per assistant. Shown to the agent with each passage it finds. 1 to 200 characters. Example: `"Biens en vente"`.
- `content_type` (enum (5 values), required): Format of the file. A .txt or .md file is a text document: send its text to [`POST /assistants/{id}/knowledge`](https://www.getrevox.com/docs/api/assistants/add-a-text-to-the-knowledge-base.md) instead. Values: `"application/pdf"`, `"image/jpeg"`, `"image/png"`, `"image/webp"`, `"image/heic"`.
- `size_bytes` (integer, required): Exact size of the file: the upload link only accepts it. > 0.

## Response 200

```json
{
  "document": {
    "id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "assistant_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
    "title": "Biens en vente",
    "file": {
      "content_type": "application/pdf",
      "url": "https://example.com"
    },
    "content": "Hello, this is Julie from Acme.",
    "status": "ready",
    "error": null,
    "created_at": "2026-11-05T09:00:00Z",
    "updated_at": "2026-11-05T09:00:00Z"
  },
  "upload_url": "https://example.com"
}
```

- `document` (object)
  - `document.id` (string)
  - `document.assistant_id` (string)
  - `document.title` (string): Name of the document, unique per assistant. Shown to the agent with each passage it finds. 1 to 200 characters. Example: `"Biens en vente"`.
  - `document.file` (object | null): The uploaded file. Null for a text document.
    - `document.file.content_type` (enum (5 values)): Values: `"application/pdf"`, `"image/jpeg"`, `"image/png"`, `"image/webp"`, `"image/heic"`.
    - `document.file.url` (string): Signed link to the original file, valid 5 minutes.
  - `document.content` (string): The searchable text: as written for a text document, the OCR of the file otherwise (empty until processed).
  - `document.status` ("processing" | "ready" | "failed"): `processing` while the text is read and indexed (a few seconds, up to a minute for a long PDF), `ready` once the agent can search it, `failed` with `error` otherwise.
  - `document.error` (string | null)
  - `document.created_at` (string): ISO 8601 timestamp.
  - `document.updated_at` (string): ISO 8601 timestamp.
- `upload_url` (string): Signed link to PUT the file to, valid 5 minutes.

## Errors

- `400` Invalid request: a field or parameter failed validation: `{"message":"Request validation failed","bodyErrors":{"issues":[{"path":["title"],"message":"Invalid input: expected string, received undefined","code":"invalid_type"}]}}`
- `404` Not found in your organization: `{"error":"Not found"}`
- Every status is explained under Errors in https://www.getrevox.com/docs/api.md#errors.