> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload files

> Store a PDF or an Excel workbook as documents.

`POST /namespaces/:namespace/files`

Send the file's bytes as the request body. Each PDF page becomes a document, and each worksheet
becomes one or more documents of Markdown tables.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.conare.ai/namespaces/docs/files?name=handbook.pdf" \
    -H "Authorization: Bearer $CONARE_API_KEY" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @handbook.pdf
  ```

  ```ts TypeScript theme={null}
  import { readFile } from "node:fs/promises";

  const file = await readFile("handbook.pdf");
  await docs.uploadFile(file, "handbook.pdf");
  ```
</CodeGroup>

```json Response theme={null}
{
  "file_id": "handbook.pdf",
  "type": "pdf",
  "pages": 2,
  "ids": ["handbook.pdf:page-1", "handbook.pdf:page-2"],
  "pages_without_text": []
}
```

## Request

Query parameters:

* `name` (string, required): The file's name.
* `id` (string): The file id, which prefixes its document ids. 1-180 characters of
  `A-Z a-z 0-9 . _ -`, starting with a letter or digit. Defaults to `name`, with other characters
  replaced by `-`.

Body: a PDF or an `.xlsx` workbook, up to 20 MiB and 2,000 pages or sheets.

## Response

* `file_id`: The file id.
* `type`: `pdf` or `xlsx`.
* `ids`: The documents written, in reading order.
* `pages` (PDF) or `sheets` (workbook): How many the file has.
* `pages_without_text` (PDF): Pages that weren't stored because they have no text layer, such as
  scans.

## Documents

| File | Document ids | Metadata |
| - | - | - |
| PDF | `<file_id>:page-1`, `<file_id>:page-2`, ... | `file`, `file_id`, `file_type`, `page` |
| Excel | `<file_id>:<sheet name>-1`, ... | `file`, `file_id`, `file_type`, `sheet` |

A large worksheet is split into several documents, each repeating the header row.

## Working with files

* **Update** a file by uploading it again with the same file id. Its old documents are replaced.
* **Search one file** with a [filter](/filters): `{ "file_id": "handbook.pdf" }`.
* **Delete** a file with a [filter delete](/delete#delete-many):
  `{ "filter": { "file_id": "handbook.pdf" } }`.

## Errors

* `415 unsupported_file`: The body is neither a PDF nor an `.xlsx`.
* `422 unreadable_file`: The file is damaged or encrypted.
* `422 no_text`: No page or sheet has text.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.