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

# Introduction

> The Doctly API enables you to convert documents to Markdown and extract structured data at scale.

The Doctly API provides two core capabilities:

1. **Document Conversion** — Convert PDFs, DOCX files, and images to clean Markdown
2. **Data Extraction** — Use custom extractors to pull structured data from documents

## Base URL

All API requests should be made to:

```
https://api.doctly.ai/api/v1
```

## Quick Start

### Convert a Document to Markdown

```bash theme={null}
curl -X POST https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "accuracy=ultra"
```

### Run an Extractor

```bash theme={null}
curl -X POST https://api.doctly.ai/api/v1/e/invoice-extractor \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"
```

## API Endpoints

### Documents

| Method   | Endpoint          | Description                            |
| -------- | ----------------- | -------------------------------------- |
| `POST`   | `/documents`      | Upload and convert a document          |
| `GET`    | `/documents`      | List all documents                     |
| `GET`    | `/documents/{id}` | Get document details and download URLs |
| `DELETE` | `/documents/{id}` | Delete a document                      |

### Extractors

| Method   | Endpoint            | Description                    |
| -------- | ------------------- | ------------------------------ |
| `GET`    | `/e`                | List available extractors      |
| `GET`    | `/e/{extractor_id}` | Get extractor details          |
| `POST`   | `/e/{slug}`         | Run an extractor on a document |
| `PUT`    | `/e/{extractor_id}` | Update extractor metadata      |
| `DELETE` | `/e/{extractor_id}` | Delete an extractor            |

## Request Format

### Authentication

All requests require a Bearer token in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

### Content Types

* **File uploads**: `multipart/form-data`
* **JSON requests**: `application/json`

## Response Format

All responses are JSON. Successful responses include the requested data:

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document.pdf",
  "status": "COMPLETED",
  "output_file_url": "https://..."
}
```

List endpoints return paginated results:

```json theme={null}
{
  "data": [...],
  "count": 150
}
```

## Error Handling

The API uses standard HTTP status codes:

| Code  | Description                                  |
| ----- | -------------------------------------------- |
| `200` | Success                                      |
| `400` | Bad request — invalid parameters             |
| `401` | Unauthorized — invalid or missing API key    |
| `404` | Not found — resource doesn't exist           |
| `413` | Payload too large — file exceeds 100MB limit |
| `422` | Validation error — check the error details   |
| `429` | Rate limit exceeded                          |
| `500` | Server error                                 |

Error responses include details:

```json theme={null}
{
  "detail": "Document not found"
}
```

Validation errors provide field-level information:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Processing Flow

Document processing is asynchronous:

1. **Upload** — Submit your document via `POST /documents` or `POST /e/{slug}`
2. **Queue** — Document enters the processing queue (`PENDING`)
3. **Process** — Document is being converted or extracted (`PROCESSING`)
4. **Complete** — Results are ready for download (`COMPLETED`)

Poll `GET /documents/{id}` to check status, or provide a `callback_url` to receive webhook notifications.

## Webhooks

Provide a `callback_url` when creating a document to receive a POST notification when processing completes:

```json theme={null}
{
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document.pdf",
  "status": "COMPLETED"
}
```

Webhook deliveries retry up to 3 times with 5-second delays.

## Rate Limits

API requests are rate-limited based on your plan. If you exceed the limit, requests return `429 Too Many Requests`. Wait and retry with exponential backoff.

## Support

* **Email**: [support@doctly.ai](mailto:support@doctly.ai)
* **GitHub**: [github.com/doctly/doctly/issues](https://github.com/doctly/doctly/issues)