Introduction

The Doctly API provides three core capabilities:

Document Conversion — Convert PDFs, DOCX files, and images to clean Markdown
Data Extraction — Use custom extractors to pull structured data from documents
Collections & Chat — Build collections of documents and ask questions against them, with page-level citations

Base URL

All API requests should be made to:

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

Quick Start

Convert a Document to Markdown

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

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

Ask a Question Against a Collection

curl -X POST https://api.doctly.ai/api/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_ids": ["COLLECTION_ID"], "query": "What is the warranty period?"}'

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

Collections & Files

Method	Endpoint	Description
`POST`	`/collections`	Create a collection
`GET`	`/collections`	List collections
`GET`	`/collections/{id}`	Get a collection
`PUT`	`/collections/{id}`	Update a collection
`DELETE`	`/collections/{id}`	Delete a collection
`POST`	`/collections/{id}/files`	Upload a file for indexing
`GET`	`/collections/{id}/files`	List files
`GET`	`/collections/{id}/files/{file_id}`	Get a file / poll processing status
`DELETE`	`/collections/{id}/files/{file_id}`	Delete a file

Chat

Method	Endpoint	Description
`POST`	`/query`	One-shot question against collections
`POST`	`/chat/sessions`	Create a chat session
`POST`	`/chat/sessions/{id}/messages`	Send a message (supports streaming)
`GET`	`/chat/sessions`	List sessions
`GET`	`/chat/sessions/{id}/messages`	Get message history
`DELETE`	`/chat/sessions/{id}`	Delete a session

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:

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

List endpoints return paginated results:

{
  "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 carry a structured error envelope alongside the legacy detail field (see Conventions for the full list of error types):

{
  "detail": "Document not found",
  "error": {
    "type": "not_found_error",
    "message": "Document not found",
    "request_id": "1f2e3d4c5b6a7980"
  }
}

Validation errors provide field-level information in detail:

{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ],
  "error": {
    "type": "invalid_request_error",
    "message": "Request validation failed",
    "request_id": "1f2e3d4c5b6a7980"
  }
}

Processing Flow

Document processing is asynchronous:

Upload — Submit your document via POST /documents or POST /e/{slug}
Queue — Document enters the processing queue (PENDING)
Process — Document is being converted or extracted (PROCESSING)
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:

{
  "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
GitHub: github.com/doctly/doctly/issues

API Overview

Documents

Extractors

Collections

Collection Files

Chat

Base URL

Quick Start

Convert a Document to Markdown

Run an Extractor

Ask a Question Against a Collection

API Endpoints

Documents

Extractors

Collections & Files

Chat

Request Format

Authentication

Content Types

Response Format

Error Handling

Processing Flow

Webhooks

Rate Limits

Support

​Base URL

​Quick Start

​Convert a Document to Markdown

​Run an Extractor

​Ask a Question Against a Collection

​API Endpoints

​Documents

​Extractors

​Collections & Files

​Chat

​Request Format

​Authentication

​Content Types

​Response Format

​Error Handling

​Processing Flow

​Webhooks

​Rate Limits

​Support

Base URL

Quick Start

Convert a Document to Markdown

Run an Extractor

Ask a Question Against a Collection

API Endpoints

Documents

Extractors

Collections & Files

Chat

Request Format

Authentication

Content Types

Response Format

Error Handling

Processing Flow

Webhooks

Rate Limits

Support