> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Files

Files [#files]

Alo Files lets you upload, organize, search, and parse files in an Alomana workspace.

An uploaded file becomes searchable once processing brings its status to `indexed`; you can then search it or download it. Start by uploading a file, then search it; [Reference](#reference) lists the headers, formats, and statuses these pages share.

* [Upload and organize files](/docs/api/alo-files/uploads-and-folders): upload files, organize folders, search file names, and get temporary download links.
* [Search files](/docs/api/alo-files/search-guide): search with natural-language questions, by meaning, keywords, file, or folder.
* [Parse a file without indexing it](/docs/api/alo-files/parse-only): extract text and tables without making the file searchable.
* [SharePoint sync](/docs/api/alo-files/sharepoint-sync): import and maintain SharePoint files.

Reference [#reference]

Headers [#headers]

```http
X-API-Key: sk-...
X-Space-Slug: your-workspace
```

| Endpoints                                              | `X-API-Key` (auth) | Workspace (`X-Space-Slug`)                                                                                                                 |
| ------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| File, folder, contents, batch, search, SharePoint sync | Required           | Required                                                                                                                                   |
| Parse-only                                             | Required           | Only for a workspace key, which must send its own workspace ([Parse a file without indexing it](/docs/api/alo-files/parse-only#workspace)) |

Supported files [#supported-files]

| Type          | Formats                         |
| ------------- | ------------------------------- |
| Documents     | PDF, DOCX, PPTX, DOC, PPT       |
| Spreadsheets  | XLSX, XLS, XLSM, XLSB, ODS, CSV |
| Text and data | JSON, HTML, Markdown, TXT       |
| Images        | PNG, JPEG                       |
| Email         | EML, MSG                        |

File statuses [#file-statuses]

| Status     | Meaning                                                       |
| ---------- | ------------------------------------------------------------- |
| `uploaded` | Uploaded, waiting to be processed.                            |
| `parsing`  | Reading the file contents.                                    |
| `parsed`   | Text or table extraction done; processing may still continue. |
| `indexing` | Preparing the file for search.                                |
| `indexed`  | Ready to search.                                              |
| `error`    | Processing failed; see `error_message` on the file.           |

* PDF, Office, and legacy Office files parse asynchronously and are searchable only once `indexed`.
* Structured files are stored as profile and table chunks; images are embedded as image records.
* A failed refresh keeps the previous indexed generation available until a replacement is ready.

Errors [#errors]

Alo Files errors are JSON `{"code", "message", "details"}`; `details` is `null` or an object such as `{"reason": "duplicate_in_folder", …}`.

| `code`              | Status | Meaning                                                                                  |
| ------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `validation_error`  | `400`  | Invalid input, such as a malformed `parent_id`                                           |
| `unsupported_mime`  | `400`  | File type not supported; `details.allowed` lists the accepted MIME types                 |
| `forbidden`         | `403`  | The credential cannot do this, such as an API key on copy-to-space                       |
| `not_found`         | `404`  | The file, folder, or sync source does not exist in this workspace                        |
| `conflict`          | `409`  | The request conflicts with the current state; `details.reason`, when set, names the case |
| `payload_too_large` | `413`  | File too large for `POST /parse/sync`                                                    |
| `parse_failed`      | `502`  | The parser failed                                                                        |
| `resource_busy`     | `503`  | Temporarily busy; `details.retryable` is `true`, so retry                                |

This differs from Central Hub's errors, which carry `detail` ([Errors](/docs/api/api-basics/errors)); Alo Files keeps that `{"detail": …}` shape only for authentication failures, a missing `X-Space-Slug`, a key used outside its workspace, and `422` request validation.