> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doctly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Documents

> Retrieve a paginated list of your documents with filtering options.

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

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication. Example: `Bearer YOUR_API_KEY`
</ParamField>

### Query Parameters

<ParamField query="skip" type="integer" default="0">
  Number of records to skip for pagination
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum number of records to return (max: 100)
</ParamField>

<ParamField query="extractor_id" type="string">
  Filter by a specific extractor ID (UUID)
</ParamField>

<ParamField query="no_extractor" type="boolean" default="false">
  When `true`, returns only documents processed without an extractor (plain Markdown conversions)
</ParamField>

<ParamField query="search" type="string">
  Search documents by filename (case-insensitive partial match)
</ParamField>

<ParamField query="date_from" type="string">
  Filter documents created on or after this date (ISO 8601 format)
</ParamField>

<ParamField query="date_to" type="string">
  Filter documents created on or before this date (ISO 8601 format)
</ParamField>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```javascript JavaScript theme={null}
  // 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`);
  ```
</CodeGroup>

## Response

<ResponseField name="data" type="array">
  Array of document objects

  <Expandable title="Document Object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID) for the document
    </ResponseField>

    <ResponseField name="file_name" type="string">
      Original filename
    </ResponseField>

    <ResponseField name="file_size" type="integer">
      Size of the file in bytes
    </ResponseField>

    <ResponseField name="page_count" type="integer">
      Number of pages in the document
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing status: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, or `EXPIRED`
    </ResponseField>

    <ResponseField name="accuracy" type="string">
      Accuracy level used: `lite` or `ultra`
    </ResponseField>

    <ResponseField name="extractor_id" type="string">
      UUID of the extractor used (if any)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of documents matching the filter criteria
</ResponseField>

## Example Responses

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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
  }
  ```

  ```json 200 OK — Empty theme={null}
  {
    "data": [],
    "count": 0
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "Invalid or missing API key"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "detail": [
      {
        "loc": ["query", "limit"],
        "msg": "ensure this value is less than or equal to 100",
        "type": "value_error.number.not_le"
      }
    ]
  }
  ```
</ResponseExample>

## Pagination Example

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```javascript JavaScript theme={null}
  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;
  }
  ```
</CodeGroup>


## OpenAPI

````yaml GET /documents
openapi: 3.1.0
info:
  title: Doctly API
  description: >-
    The Doctly API enables you to programmatically convert PDF documents to
    Markdown and extract structured data using custom extractors.
  version: 1.0.0
  contact:
    email: support@doctly.ai
servers:
  - url: https://api.doctly.ai/api/v1
    description: Production server
security:
  - bearerAuth: []
paths:
  /documents:
    get:
      tags:
        - Documents
      summary: List Documents
      description: Retrieve a paginated list of your documents with optional filtering
      operationId: listDocuments
      parameters:
        - name: skip
          in: query
          description: Number of records to skip for pagination
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Maximum number of records to return (max 100)
          schema:
            type: integer
            default: 100
            maximum: 100
        - name: extractor_id
          in: query
          description: Filter by extractor ID
          schema:
            type: string
            format: uuid
        - name: no_extractor
          in: query
          description: Filter for documents without an extractor (plain conversions)
          schema:
            type: boolean
            default: false
        - name: search
          in: query
          description: Search by filename
          schema:
            type: string
        - name: date_from
          in: query
          description: Filter by start date (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: date_to
          in: query
          description: Filter by end date (ISO 8601)
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: List of documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentsPublic'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DocumentsPublic:
      type: object
      required:
        - data
        - count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DocumentPublic'
        count:
          type: integer
    Error:
      type: object
      properties:
        detail:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  loc:
                    type: array
                    items:
                      type: string
                  msg:
                    type: string
                  type:
                    type: string
    DocumentPublic:
      type: object
      required:
        - id
        - file_name
        - file_size
        - status
        - created_at
      properties:
        id:
          type: string
          format: uuid
        file_name:
          type: string
        file_size:
          type: integer
        page_count:
          type: integer
          nullable: true
        status:
          $ref: '#/components/schemas/DocumentStatus'
        accuracy:
          $ref: '#/components/schemas/AccuracyLevel'
        extractor_id:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
    DocumentStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - COMPLETED
        - FAILED
        - EXPIRED
      description: Current processing status of a document
    AccuracyLevel:
      type: string
      enum:
        - lite
        - ultra
      description: Processing accuracy level
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication using Bearer token

````