Skip to main content
Get Document
curl --request GET \
  --url https://api.doctly.ai/api/v1/documents/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "annual-report.pdf",
  "file_size": 4194304,
  "page_count": 48,
  "status": "COMPLETED",
  "accuracy": "ultra",
  "extractor_id": null,
  "output_file_url": "https://doctly-output.s3.amazonaws.com/...",
  "file_url": "https://doctly-files.s3.amazonaws.com/...",
  "output_file_name": "annual-report.md",
  "created_at": "2024-03-21T13:45:00Z"
}
Retrieve a specific document by its ID. When the document status is COMPLETED, this endpoint returns signed URLs for downloading the processed output and original file.

​
Request

​
Headers

​
Authorization
string
required
Bearer token authentication. Example: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
The unique identifier (UUID) of the document

​
Example Request

curl https://api.doctly.ai/api/v1/documents/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "annual-report.pdf",
  "file_size": 4194304,
  "page_count": 48,
  "status": "COMPLETED",
  "accuracy": "ultra",
  "extractor_id": null,
  "output_file_url": "https://doctly-output.s3.amazonaws.com/...",
  "file_url": "https://doctly-files.s3.amazonaws.com/...",
  "output_file_name": "annual-report.md",
  "created_at": "2024-03-21T13:45:00Z"
}

​
Processing Status

Documents progress through these states:
StatusDescription
PENDINGDocument is queued for processing
PROCESSINGDocument is actively being processed
COMPLETEDProcessing finished successfully — download URLs available
FAILEDProcessing failed — check the original file for issues
EXPIREDDocument and files have been cleaned up
Download URLs are temporary. Signed URLs expire after a period of time. Fetch new URLs by calling this endpoint again if needed.

​
Polling for Completion

import time
import requests

def wait_for_document(doc_id: str, api_key: str, timeout: int = 300):
    """Poll until document processing completes."""
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://api.doctly.ai/api/v1/documents/{doc_id}"
    
    start = time.time()
    while time.time() - start < timeout:
        response = requests.get(url, headers=headers)
        document = response.json()
        
        if document["status"] == "COMPLETED":
            return document
        elif document["status"] == "FAILED":
            raise Exception("Document processing failed")
        
        time.sleep(5)
    
    raise TimeoutError("Document processing timed out")

# Usage
doc = wait_for_document("123e4567-...", "YOUR_API_KEY")
print(f"Download: {doc['output_file_url']}")

Authorizations

​
Authorization
string
header
required

API key authentication using Bearer token

Path Parameters

​
id
string<uuid>
required

Document ID

Response

Document details

​
id
string<uuid>
required
​
file_name
string
required
​
file_size
integer
required
​
status
enum<string>
required

Current processing status of a document

Available options:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
EXPIRED
​
created_at
string<date-time>
required
​
page_count
integer | null
​
accuracy
enum<string>

Processing accuracy level

Available options:
lite,
ultra
​
extractor_id
string<uuid> | null
​
output_file_url
string<uri> | null

Signed URL to download processed output

​
file_url
string<uri> | null

Signed URL to download original file

​
output_file_name
string | null