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

# File Upload

> Upload documents directly via API

Upload files to a collection in a single request. The file is stored, validated, and immediately queued for parsing and knowledge extraction.

## Upload a file

```bash theme={null}
curl -X POST https://aigmented.io/api/v1/collections/49/files/upload \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf"
```

Response:

```json theme={null}
{
  "file_id": 250,
  "filename": "document.pdf",
  "status": "processing",
  "content_type": "application/pdf",
  "size_bytes": 1048576
}
```

The file enters the processing pipeline automatically. Check the collection status to know when extraction is complete.

## Supported formats

| Format | Extensions | MIME Type                                                                 |
| ------ | ---------- | ------------------------------------------------------------------------- |
| PDF    | `.pdf`     | `application/pdf`                                                         |
| Excel  | `.xlsx`    | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       |
| CSV    | `.csv`     | `text/csv`                                                                |
| Word   | `.docx`    | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |

## Validation

Files are validated in three layers before upload:

1. **Extension** — must be one of the supported formats above
2. **MIME type** — must match the expected type for the extension
3. **Magic bytes** — file header is checked to confirm actual format (prevents renaming executables to `.pdf`)

Executable files (`.exe`, `.sh`, `.bat`, `.dll`, etc.) and binary files (ELF, Mach-O) are always rejected.

## Limits

| Limit           | Value                |
| --------------- | -------------------- |
| Max file size   | 50 MB                |
| Allowed formats | PDF, XLSX, CSV, DOCX |

## Error codes

| Status                       | Meaning                                         |
| ---------------------------- | ----------------------------------------------- |
| `201 Created`                | File uploaded and processing started            |
| `400 Bad Request`            | No file provided (use field name `file`)        |
| `413 Payload Too Large`      | File exceeds 50 MB                              |
| `415 Unsupported Media Type` | File format not allowed or magic bytes mismatch |

## Processing pipeline

After upload, the file goes through the processing pipeline:

1. **Parsing** — document is parsed into zones (sections, tables, etc.)
2. **Extraction** — knowledge cards are extracted from zones using LLM
3. **Indexing** — cards are embedded and indexed in the vector database

Reference files (`.xlsx`, `.csv`) follow a separate pipeline optimized for tabular data.

The collection status changes to `processing` during this time and `processed` when complete.