Skip to main content
curl -X POST https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "accuracy=ultra"
POST /api/v1/documents Upload a document to convert it to Markdown or process it with a custom extractor. The API supports PDF, DOCX, and image files up to 100MB.

​
Request

​
Headers

​
Authorization
string
required
Bearer token authentication. Example: Bearer YOUR_API_KEY
​
Content-Type
string
required
Must be multipart/form-data

​
Body Parameters

​
file
file
The document file to process. Supported formats: PDF, DOCX, PNG, JPG, JPEG, WEBP, GIF.
Provide either file or url, not both.
​
url
string
URL to download the document from. The file will be fetched and processed.
Provide either file or url, not both.
​
accuracy
string
default:"lite"
Processing accuracy level for Markdown conversion:
  • lite — Fast processing with great accuracy (default)
  • ultra — Highest accuracy for complex documents
​
extractor_id
string
UUID of a custom extractor to use instead of standard Markdown conversion.
​
page_separator
boolean
default:"true"
Include page break markers (---) in the Markdown output.
​
skip_images
boolean
default:"false"
When true, images are not extracted or transcribed from the document.
​
callback_url
string
Webhook URL to receive a POST request when processing completes.

​
EU Endpoint

For data residency requirements, an EU-based endpoint is available at api.eu.doctly.ai. Documents processed through this endpoint are stored and processed entirely within the European Union.
The EU endpoint only supports the url parameter. Direct file uploads using the file parameter are not available on this endpoint.
curl -X POST https://api.eu.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "url=https://example.com/report.pdf" \
  -F "accuracy=ultra"

​
Example Requests

​
Convert 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"

​
Convert from URL

curl -X POST https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "url=https://example.com/report.pdf" \
  -F "accuracy=lite"

​
Use Custom Extractor

curl -X POST https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "extractor_id=987fcdeb-a654-3210-9876-543210987654"

​
Response

​
Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document.pdf",
  "file_size": 1048576,
  "page_count": 12,
  "status": "PENDING",
  "accuracy": "ultra",
  "created_at": "2024-03-21T13:45:00Z"
}

​
Webhooks

When callback_url is provided, a POST request is sent when processing completes: 
{
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document.pdf",
  "status": "COMPLETED"
}
Webhooks retry up to 3 times with 5-second delays if delivery fails. URLs must be HTTPS and publicly accessible.

​
Next Steps

After creating a document, poll Get Document until status is COMPLETED or FAILED. The output_file_url provides a signed download link for the result. 
# Poll until complete
DOC_ID="123e4567-e89b-12d3-a456-426614174000"
while true; do
  RESP=$(curl -s https://api.doctly.ai/api/v1/documents/$DOC_ID \
    -H "Authorization: Bearer YOUR_API_KEY")
  STATUS=$(echo $RESP | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    echo $RESP | jq '.output_file_url'
    break
  fi
  sleep 5
done