/api/v1/documents/{id}
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
string
required
Bearer token authentication. Example:
Bearer YOUR_API_KEYPath 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"
import requests
doc_id = "123e4567-e89b-12d3-a456-426614174000"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
f"https://api.doctly.ai/api/v1/documents/{doc_id}",
headers=headers
)
document = response.json()
print(f"Status: {document['status']}")
if document['status'] == 'COMPLETED':
print(f"Download: {document['output_file_url']}")
const docId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.doctly.ai/api/v1/documents/${docId}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const document = await response.json();
console.log(`Status: ${document.status}`);
if (document.status === 'COMPLETED') {
console.log(`Download: ${document.output_file_url}`);
}
Response
Show Document Object
Show Document Object
string
Unique identifier (UUID) for the document
string
Original filename of the uploaded document
integer
Size of the file in bytes
integer
Number of pages in the document
string
Processing status:
PENDING, PROCESSING, COMPLETED, FAILED, or EXPIREDstring
Accuracy level used:
lite or ultrastring
UUID of the extractor used (if applicable)
object
Extractor details when using custom extraction
string
Signed URL to download the processed output (Markdown or extraction result). Available when status is
COMPLETED.string
Signed URL to download the original uploaded file. Available when status is
COMPLETED.string
Filename of the processed output (e.g.,
document.md or document.json)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"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"file_name": "invoice.pdf",
"file_size": 524288,
"page_count": 2,
"status": "COMPLETED",
"accuracy": null,
"extractor_id": "987fcdeb-a654-3210-9876-543210987654",
"extractor": {
"id": "987fcdeb-a654-3210-9876-543210987654",
"name": "Invoice Extractor",
"slug": "invoice-extractor",
"cost_type": "PER_PAGE",
"cost_credits": 5
},
"output_file_url": "https://doctly-output.s3.amazonaws.com/...",
"file_url": "https://doctly-files.s3.amazonaws.com/...",
"output_file_name": "invoice.json",
"created_at": "2024-03-21T13:45:00Z"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"file_name": "document.pdf",
"file_size": 1048576,
"page_count": 12,
"status": "PROCESSING",
"accuracy": "lite",
"extractor_id": null,
"output_file_url": null,
"file_url": null,
"output_file_name": null,
"created_at": "2024-03-21T14:00:00Z"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"file_name": "corrupted.pdf",
"file_size": 1048576,
"page_count": null,
"status": "FAILED",
"accuracy": "lite",
"extractor_id": null,
"output_file_url": null,
"file_url": null,
"output_file_name": null,
"created_at": "2024-03-21T14:00:00Z"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"file_name": "old-document.pdf",
"file_size": 1048576,
"page_count": 10,
"status": "EXPIRED",
"accuracy": "lite",
"extractor_id": null,
"output_file_url": null,
"file_url": null,
"output_file_name": null,
"created_at": "2024-01-15T09:00:00Z"
}
{
"detail": "Document not found"
}
{
"detail": [
{
"loc": ["path", "id"],
"msg": "value is not a valid uuid",
"type": "type_error.uuid"
}
]
}
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']}")
async function waitForDocument(docId, apiKey, timeout = 300000) {
const headers = { 'Authorization': `Bearer ${apiKey}` };
const url = `https://api.doctly.ai/api/v1/documents/${docId}`;
const start = Date.now();
while (Date.now() - start < timeout) {
const response = await fetch(url, { headers });
const document = await response.json();
if (document.status === 'COMPLETED') {
return document;
} else if (document.status === 'FAILED') {
throw new Error('Document processing failed');
}
await new Promise(r => setTimeout(r, 5000));
}
throw new Error('Document processing timed out');
}
// Usage
const doc = await waitForDocument('123e4567-...', 'YOUR_API_KEY');
console.log(`Download: ${doc.output_file_url}`);