List Documents

GET /api/v1/documents Retrieve all documents associated with your account. Results are paginated and can be filtered by date, filename, or extractor.

Request

Headers

string

required

Bearer token authentication. Example: Bearer YOUR_API_KEY

Query Parameters

integer

default:"0"

Number of records to skip for pagination

integer

default:"100"

Maximum number of records to return (max: 100)

string

Filter by a specific extractor ID (UUID)

boolean

default:"false"

When true, returns only documents processed without an extractor (plain Markdown conversions)

string

Search documents by filename (case-insensitive partial match)

string

Filter documents created on or after this date (ISO 8601 format)

string

Filter documents created on or before this date (ISO 8601 format)

Example Requests

# Basic list
curl https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY"

# With pagination
curl "https://api.doctly.ai/api/v1/documents?skip=20&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by filename
curl "https://api.doctly.ai/api/v1/documents?search=invoice" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by date range
curl "https://api.doctly.ai/api/v1/documents?date_from=2024-01-01&date_to=2024-03-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Basic list
response = requests.get(
    "https://api.doctly.ai/api/v1/documents",
    headers=headers
)

# With filters
response = requests.get(
    "https://api.doctly.ai/api/v1/documents",
    headers=headers,
    params={
        "search": "invoice",
        "date_from": "2024-01-01",
        "limit": 50
    }
)

data = response.json()
print(f"Found {data['count']} documents")
for doc in data['data']:
    print(f"  {doc['file_name']} - {doc['status']}")

// Basic list
const response = await fetch('https://api.doctly.ai/api/v1/documents', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

// With filters
const params = new URLSearchParams({
  search: 'invoice',
  date_from: '2024-01-01',
  limit: '50'
});

const filtered = await fetch(
  `https://api.doctly.ai/api/v1/documents?${params}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await filtered.json();
console.log(`Found ${data.count} documents`);

Response

array

Array of document objects

Show Document Object

string

Unique identifier (UUID) for the document

string

Original filename

integer

Size of the file in bytes

integer

Number of pages in the document

string

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

string

Accuracy level used: lite or ultra

string

UUID of the extractor used (if any)

string

ISO 8601 timestamp of creation

integer

Total number of documents matching the filter criteria

Example Responses

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "file_name": "quarterly-report.pdf",
      "file_size": 2097152,
      "page_count": 24,
      "status": "COMPLETED",
      "accuracy": "ultra",
      "extractor_id": null,
      "created_at": "2024-03-21T13:45:00Z"
    },
    {
      "id": "987fcdeb-a654-3210-9876-543210987654",
      "file_name": "invoice-march.pdf",
      "file_size": 524288,
      "page_count": 2,
      "status": "COMPLETED",
      "accuracy": null,
      "extractor_id": "abc12345-e89b-12d3-a456-426614174000",
      "created_at": "2024-03-20T09:30:00Z"
    },
    {
      "id": "456def78-e89b-12d3-a456-426614174000",
      "file_name": "contract.docx",
      "file_size": 1048576,
      "page_count": null,
      "status": "PROCESSING",
      "accuracy": "lite",
      "extractor_id": null,
      "created_at": "2024-03-21T14:00:00Z"
    }
  ],
  "count": 156
}

{
  "data": [],
  "count": 0
}

{
  "detail": "Invalid or missing API key"
}

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

Pagination Example

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
all_documents = []
skip = 0
limit = 100

while True:
    response = requests.get(
        "https://api.doctly.ai/api/v1/documents",
        headers=headers,
        params={"skip": skip, "limit": limit}
    ).json()
    
    all_documents.extend(response["data"])
    
    if len(all_documents) >= response["count"]:
        break
    
    skip += limit

print(f"Retrieved {len(all_documents)} documents")

async function getAllDocuments() {
  const headers = { 'Authorization': 'Bearer YOUR_API_KEY' };
  const allDocuments = [];
  let skip = 0;
  const limit = 100;
  
  while (true) {
    const response = await fetch(
      `https://api.doctly.ai/api/v1/documents?skip=${skip}&limit=${limit}`,
      { headers }
    );
    const data = await response.json();
    
    allDocuments.push(...data.data);
    
    if (allDocuments.length >= data.count) break;
    skip += limit;
  }
  
  return allDocuments;
}

API Overview

Documents

Extractors

Collections

Collection Files

Chat

List Documents

Request

Headers

Query Parameters

Example Requests

Response

Example Responses

​Request

​Headers

​Query Parameters

​Example Requests

​Response

​Example Responses

​Pagination Example

Request

Headers

Query Parameters

Example Requests

Response

Example Responses

Pagination Example