---
title: "Upload a file"
description: "A document or an image, sent as the request body and read in the background."
url: "https://openemail.uk/docs/api/knowledge/files"
area: "API"
category: "Mailbox"
---

# Upload a file

A document or an image, sent as the request body and read in the background.

`POST /knowledge/files`

## POST /knowledge/files

A document or an image, sent as the request body and read in the background.

## Example

Needs `knowledge:write`. Send the file itself as the body with its `Content-Type`, and name it with `filename` or an `X-Filename` header. `scope` and `title` go in the query too. A document can be up to 20 MB and an image up to 10 MB. Answers 201 with the file, `queued`.

**curl**

```
curl -X POST "$OE/knowledge/files?filename=price-list.pdf&scope=sales@acme.com" -H "$AUTH" \
  -H "Content-Type: application/pdf" --data-binary @price-list.pdf
```

**Response**

```
{
  "object": "knowledge_item",
  "id": "kb_9a4d2c7e1b5f3086d2e4a19c",
  "kind": "file",
  "scope": "sales@acme.com",
  "level": "address",
  "title": "price-list",
  "url": null,
  "fileName": "price-list.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 482113,
  "pinned": false,
  "status": "queued",
  "failure": null,
  "chunks": 0,
  "chars": 0,
  "origin": "api",
  "createdBy": "usr_5f2a9c71",
  "createdAt": "2026-10-08T09:15:30.000Z",
  "updatedAt": "2026-10-08T09:15:30.000Z",
  "indexedAt": null
}
```

> The extension of the name tells the kind of file when the `Content-Type` is generic. A kind of file that cannot be read is a 422 `knowledge_file_unsupported`, an empty one a 422 `knowledge_file_empty`, and one over the limit a 413 `knowledge_file_too_large`.

> A file with no text in it ends `failed` with `failure: "empty"`. Sending the same file twice stores it twice.

## Reference

- [`POST /knowledge/files`](https://openemail.uk/docs/api/reference/knowledge#post-knowledge-files): full reference