Introduction - Doctly

The Doctly API provides two core capabilities:

Document Conversion — Convert PDFs, DOCX files, and images to clean Markdown
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

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"

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:

{
  "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 include details:

{
  "detail": "Document not found"
}

Validation errors provide field-level information:

{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

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

​Base URL

​Quick Start

​Convert a Document to Markdown

​Run an Extractor

​API Endpoints

​Documents

​Extractors

​Request Format

​Authentication

​Content Types

​Response Format

​Error Handling

​Processing Flow

​Webhooks

​Rate Limits

​Support