Skip to main content
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

curl -X POST https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -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 "[email protected]"

​
API Endpoints

​
Documents

MethodEndpointDescription
POST/documentsUpload and convert a document
GET/documentsList all documents
GET/documents/{id}Get document details and download URLs
DELETE/documents/{id}Delete a document

​
Extractors

MethodEndpointDescription
GET/eList 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:
CodeDescription
200Success
400Bad request — invalid parameters
401Unauthorized — invalid or missing API key
404Not found — resource doesn’t exist
413Payload too large — file exceeds 100MB limit
422Validation error — check the error details
429Rate limit exceeded
500Server 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:
  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: 
{
  "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