Create Document

Upload a new document for processing. This endpoint supports asynchronous processing with status updates available through polling or webhooks.

Request

Headers

Authorization · string · required

Bearer token authentication. See our Authentication guide for more details. Example: Bearer YOUR_API_KEY

Content-Type · string · required

Must be multipart/form-data

Body Parameters

file · file · required

A document file to process. The file must be a PDF, Docx, or Image file.

accuracy · string · default: "lite"

Markdown conversion with processing accuracy level. Options: lite or ultra.

• lite: Faster processing with great accuracy
• ultra: Highest accuracy, but slower processing

extractor_id · string · default: "lite"

The ID of the custom extractor to use with your document.

page_separator · boolean · default: "true"

Whether to include page separators in the output.

skip_images · boolean · default: "false"

Whether to skip image extraction from the document.

callback_url · string

Optional webhook URL to receive processing status updates.

Example Request of Document to Markdown

cURL

curl -X POST https://api.doctly.ai/api/v1/documents/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document2.pdf" \
  -F "accuracy=ultra" \
  -F "callback_url=https://your-domain.com/webhook"

Response

object · object

Created document object.

Show Document Object

id · string

Unique identifier for the document

file_name · string

Original filename

file_size · integer

Size of the file in bytes

created_at · string

ISO 8601 timestamp of creation

status · string

Current processing status: PENDING, PROCESSING, COMPLETED, FAILED, or EXPIRED

accuracy · string

Selected accuracy level: lite or ultra

page_count · integer

Number of pages in the document (available after processing)

Example Responses

200 OK

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

Webhook Notifications

If a callback_url is provided, you will receive a POST request when processing has completed:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document.pdf"
}

Webhook URLs must be HTTPS and publicly accessible.

Webhook Failure Handling

If the webhook delivery fails:

• The system will automatically retry up to 3 times
• Each retry attempt waits 5 seconds before trying again

Next Step: Poll for Completion

After you create a document the status will be PENDING. Call Get Document periodically using the returned id until status changes to COMPLETED or FAILED. The output_file_url field will then be available for download.

cURL

# Poll every 5 s until status==COMPLETED or status==FAILED
DOC_ID="123e4567-e89b-12d3-a456-426614174000"
while true; do
  STATUS=$(curl -s https://api.doctly.ai/api/v1/documents/$DOC_ID \
    -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    break
  fi
  sleep 5
done