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

# List Docs

> Flexible document listing with aggregates, projections, and advanced pagination.

Alias: `/documents` and `/documents/list_docs` share this handler.

**Supported operators**: `$and`, `$or`, `$nor`, `$not`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`,
`$in`, `$nin`, `$exists`, `$type`, `$regex`, `$contains`.

**Implicit equality** (backwards compatible, JSONB containment):
```json
{"status": "active"}
```

**Explicit operators** (typed comparisons for number, decimal, datetime, date):
```json
{"priority": {"$gte": 40}, "end_date": {"$lt": "2025-01-01"}}
```

Use `document_filters` with a `filename` key to filter the filename column:
```json
{"filename": {"$regex": {"pattern": "^report_.*\.pdf$", "flags": "i"}}}
```

Use `folder_name` and `end_user_id` query parameters to scope system metadata.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/morphik/openapi.documented.yml post /documents
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /documents:
    post:
      tags:
        - Documents
      summary: List Docs
      description: >-
        Flexible document listing with aggregates, projections, and advanced
        pagination.


        Alias: `/documents` and `/documents/list_docs` share this handler.


        **Supported operators**: `$and`, `$or`, `$nor`, `$not`, `$eq`, `$ne`,
        `$gt`, `$gte`, `$lt`, `$lte`,

        `$in`, `$nin`, `$exists`, `$type`, `$regex`, `$contains`.


        **Implicit equality** (backwards compatible, JSONB containment):

        ```json

        {"status": "active"}

        ```


        **Explicit operators** (typed comparisons for number, decimal, datetime,
        date):

        ```json

        {"priority": {"$gte": 40}, "end_date": {"$lt": "2025-01-01"}}

        ```


        Use `document_filters` with a `filename` key to filter the filename
        column:

        ```json

        {"filename": {"$regex": {"pattern": "^report_.*\.pdf$", "flags": "i"}}}

        ```


        Use `folder_name` and `end_user_id` query parameters to scope system
        metadata.
      operationId: list_docs_documents_post
      parameters:
        - name: folder_name
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - items:
                  type: string
                type: array
              - type: 'null'
            openapi_extra:
              style: form
              explode: true
            title: Folder Name
        - name: folder_depth
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: >-
              Folder scope depth: 0/None = exact, -1 = all descendants, n > 0 =
              include descendants up to n levels.
            title: Folder Depth
          description: >-
            Folder scope depth: 0/None = exact, -1 = all descendants, n > 0 =
            include descendants up to n levels.
        - name: end_user_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: End User Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListDocsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDocsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Morphik from 'morphik';

            const client = new Morphik({
              apiKey: process.env['MORPHIK_API_KEY'], // This is the default and can be omitted
            });

            const documents = await client.documents.list();

            console.log(documents.limit);
        - lang: cURL
          source: |-
            curl https://api.morphik.ai/documents \
                -H 'Content-Type: application/json' \
                -H "Authorization: Bearer $MORPHIK_API_KEY" \
                -d '{}'
components:
  schemas:
    ListDocsRequest:
      properties:
        document_filters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Document Filters
          description: >-
            Metadata filters with operator support: $and, $or, $nor, $not, $eq,
            $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $type, $regex,
            $contains. Implicit equality uses JSONB containment; explicit
            operators support typed comparisons. Reserved key: 'filename'
            filters the filename column.
        skip:
          type: integer
          minimum: 0
          title: Skip
          description: Number of documents to skip
          default: 0
        limit:
          type: integer
          minimum: 0
          title: Limit
          description: Maximum number of documents to return
          default: 100
        return_documents:
          type: boolean
          title: Return Documents
          description: When false, only aggregates are returned
          default: true
        include_total_count:
          type: boolean
          title: Include Total Count
          description: Include total number of matching documents when true
          default: false
        include_status_counts:
          type: boolean
          title: Include Status Counts
          description: Include document counts grouped by processing status when true
          default: false
        include_folder_counts:
          type: boolean
          title: Include Folder Counts
          description: Include document counts grouped by folder when true
          default: false
        completed_only:
          type: boolean
          title: Completed Only
          description: >-
            When true, only documents with completed processing status are
            returned and counted
          default: false
        sort_by:
          anyOf:
            - type: string
              enum:
                - created_at
                - updated_at
                - filename
                - external_id
            - type: 'null'
          title: Sort By
          description: Field to sort the results by
          default: updated_at
        sort_direction:
          type: string
          enum:
            - asc
            - desc
          title: Sort Direction
          description: Sort direction for the results
          default: desc
        fields:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Fields
          description: >-
            Optional list of fields to project for each document (dot notation
            supported). Derived fields such as 'page_count' are also supported.
      type: object
      title: ListDocsRequest
      description: >-
        Flexible request model for listing documents with projection and
        aggregates.
    ListDocsResponse:
      properties:
        documents:
          items: {}
          type: array
          title: Documents
        skip:
          type: integer
          title: Skip
        limit:
          type: integer
          title: Limit
        returned_count:
          type: integer
          title: Returned Count
        total_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Count
        has_more:
          type: boolean
          title: Has More
          default: false
        next_skip:
          anyOf:
            - type: integer
            - type: 'null'
          title: Next Skip
        status_counts:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Status Counts
        folder_counts:
          anyOf:
            - items:
                $ref: '#/components/schemas/FolderCount'
              type: array
            - type: 'null'
          title: Folder Counts
      type: object
      required:
        - skip
        - limit
        - returned_count
      title: ListDocsResponse
      description: Flexible response for listing documents with aggregates.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FolderCount:
      properties:
        folder:
          anyOf:
            - type: string
            - type: 'null'
          title: Folder
        count:
          type: integer
          title: Count
      type: object
      required:
        - folder
        - count
      title: FolderCount
      description: Count of documents grouped by folder name.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````