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

# Documents & Uploads

> Upload files to a knowledge store for automatic parsing, chunking, and embedding.

Upload documents directly when you have one-off files — a PDF policy handbook, an internal wiki export, a set of FAQs — that you want agents to search. Unlike connectors (which sync a live data source on a schedule), document uploads are a manual, point-in-time action. If the file rarely changes or you just need it indexed once, this is the fastest path.

Documents are files you add directly to a knowledge store. The platform parses, chunks, and embeds them automatically so content becomes searchable without preprocessing.

## Supported formats

| Format | Notes                                                  |
| ------ | ------------------------------------------------------ |
| PDF    | Text-extractable only; image-only PDFs will not chunk. |
| DOCX   | Microsoft Word (`.docx`).                              |
| TXT    | Plain text.                                            |
| MD     | Markdown.                                              |
| HTML   | Web pages and exported HTML.                           |
| JSON   | Structured data; flattened for chunking.               |
| CSV    | Tabular data; rows become chunks.                      |

<Warning>
  Only the formats above are supported. DOC, XML, and XLSX are **not** accepted. Maximum file size: **100 MB**.
</Warning>

## How it works

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/doc-ingestion.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=25689e0b53979a8e91ae7c092d5dee29" alt="Document ingestion pipeline" width="1536" height="1024" data-path="assets/diagrams/doc-ingestion.png" />

## Upload a document

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/knowledge/YOUR_STORE_ID/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@handbook.pdf"
```

### Response

<ResponseField name="id" type="string">
  Unique document identifier.
</ResponseField>

<ResponseField name="filename" type="string">
  Original filename.
</ResponseField>

<ResponseField name="size_bytes" type="integer">
  File size in bytes.
</ResponseField>

<ResponseField name="status" type="string">
  Processing status (e.g., `processing`, `completed`, `failed`).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 upload timestamp.
</ResponseField>

## List documents

```bash theme={"dark"}
curl "https://api.hexelstudio.com/data/v1/knowledge/YOUR_STORE_ID/documents?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"
```

## Delete a document

```bash theme={"dark"}
curl -X DELETE https://api.hexelstudio.com/data/v1/knowledge/YOUR_STORE_ID/documents/YOUR_DOCUMENT_ID \
  -H "Authorization: Bearer $TOKEN"
```

<Note>
  Deleting a document removes its chunks from the knowledge store. Search results will no longer include content from that file.
</Note>

## Errors

| `code`                   | HTTP | When                                                  |
| ------------------------ | ---- | ----------------------------------------------------- |
| `VALIDATION`             | 400  | Unsupported format, or the file exceeds 100 MB.       |
| `AUTH.PERMISSION_DENIED` | 403  | Missing `data-platform:knowledge:write`.              |
| `RESOURCE.NOT_FOUND`     | 404  | The target knowledge store or document doesn't exist. |

## Security

| Concern           | Detail                                                                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Upload permission | `data-platform:knowledge:write` is required to upload, delete, or manage documents.                                                                     |
| Read access       | Documents inherit the scope of their knowledge store. Any agent with `data-platform:knowledge:read` on the store can retrieve their content via search. |
| Text extraction   | Content must be text-extractable. Image-only PDFs or encrypted files will not index correctly.                                                          |
| Sensitive data    | Do not upload secrets, credentials, or data you cannot share with all agents that have read access to the store.                                        |

## Rate limits

10,000 requests per organization per hour. Maximum file size: 100 MB.

<AccordionGroup>
  <Accordion title="Common errors">
    | Code  | Meaning                                  |
    | ----- | ---------------------------------------- |
    | `400` | Unsupported file format or missing file. |
    | `413` | File exceeds 100 MB limit.               |
    | `404` | Knowledge store not found.               |
    | `429` | Rate limit exceeded.                     |
  </Accordion>

  <Accordion title="Processing time">
    Small text files process in seconds. Large PDFs (50+ MB) may take several minutes. Poll the document status or use the Syncs view to monitor progress.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Knowledge Stores" icon="book" href="/docs/data-platform/knowledge-stores">
    Where uploaded documents live.
  </Card>

  <Card title="Connectors" icon="plug" href="/docs/data-platform/connectors">
    Automate ingestion from S3.
  </Card>

  <Card title="Syncs" icon="arrows-rotate" href="/docs/data-platform/syncs">
    Track ingestion runs.
  </Card>

  <Card title="Data Platform Overview" icon="database" href="/docs/data-platform/overview">
    The full data model.
  </Card>
</CardGroup>

## Next steps

Continue to [Syncs](/docs/data-platform/syncs).