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

​
Example Requests

​
Convert to Markdown

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