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"
}

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

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

Show Document Object

string

Unique identifier (UUID) for the document

file_name

string

Original filename of the uploaded document

file_size

integer

Size of the file in bytes

page_count

integer

Number of pages in the document

status

string

Processing status: PENDING, PROCESSING, COMPLETED, FAILED, or EXPIRED

accuracy

string

Accuracy level used: lite or ultra

extractor_id

string

UUID of the extractor used (if applicable)

extractor

object

Extractor details when using custom extraction

output_file_url

string

Signed URL to download the processed output (Markdown or extraction result). Available when status is COMPLETED.

file_url

string

Signed URL to download the original uploaded file. Available when status is COMPLETED.

output_file_name

string

Filename of the processed output (e.g., document.md or document.json)

created_at

string

ISO 8601 timestamp of creation

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:

Status	Description
`PENDING`	Document is queued for processing
`PROCESSING`	Document is actively being processed
`COMPLETED`	Processing finished successfully — download URLs available
`FAILED`	Processing failed — check the original file for issues
`EXPIRED`	Document 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

string<uuid>

required

Document ID

Response

Document details

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

List Documents Delete Document

​Request

​Headers

​Path Parameters

​Example Request

​Response

​Example Responses

​Processing Status

​Polling for Completion

Authorizations

Path Parameters

Response

Request

Headers

Path Parameters

Example Request

Response

Example Responses

Processing Status

Polling for Completion