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

# List the documents in a collection

> A page of the documents in one collection, newest first. Metadata only: no endpoint returns a document's text, and collection_id is required, never optional.

Returns document metadata only. No endpoint returns a document's text.

`collection_id` is required. Leaving it out returns `400` rather than an unfiltered list, and a collection that is not in your organization returns `404`. Documents are ordered by when they were first seen, newest first. Page through the results with `limit` and `offset`. See [Pagination](/api-reference/pagination).

`limit` and `offset` are clamped rather than refused. A `limit` below `1` becomes `1`, a `limit` above `100` becomes `100`, and a negative `offset` becomes `0`. A value that is not a whole number returns `400`. Any role in the organization can list documents.

<ParamField query="collection_id" type="string" required>
  Collection ID (a UUID). A malformed value returns `400`.
</ParamField>

<ParamField query="source_id" type="string">
  Return only documents produced by this source. An ID that matches none of the collection's sources
  returns an empty page.
</ParamField>

<ParamField query="include_deleted" type="boolean" default="false">
  Include documents that have disappeared from their source (`status` `deleted`). Only `true`, `1`
  or `yes` turn it on. Any other value counts as `false`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Page size, from `1` to `100`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of documents to skip.
</ParamField>

## Response

<ResponseField name="data" type="object[]" required>
  The page of documents.

  <Expandable title="properties">
    <ResponseField name="id" type="string" required>
      Document ID (a UUID). It stays the same across syncs for the same path in the same source.
    </ResponseField>

    <ResponseField name="collection_id" type="string" required>
      Collection the document belongs to.
    </ResponseField>

    <ResponseField name="source_id" type="string" required>
      Source that produced the document.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Document title.
    </ResponseField>

    <ResponseField name="path" type="string" required>
      The document's path within its source, such as a repository path or an uploaded filename.
    </ResponseField>

    <ResponseField name="content_type" type="string" required>
      `markdown`, `plain_text`, `restructured_text`, `source_code`, `html`, `pdf` or `docx`.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      `active`, or `deleted` when the document is no longer in its source. Deleted documents are not
      used in answers.
    </ResponseField>

    <ResponseField name="source_url" type="string | null" required>
      A link to the document at its source, when the source has one.
    </ResponseField>

    <ResponseField name="source_version" type="string" required>
      The source version the stored content was read at, such as a commit SHA.
    </ResponseField>

    <ResponseField name="first_seen_at" type="string | null" required>
      ISO 8601 timestamp, in UTC, of the first sync that found the document.
    </ResponseField>

    <ResponseField name="last_seen_at" type="string | null" required>
      ISO 8601 timestamp, in UTC, of the latest sync that found the document.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required>
  Number of documents matching the filters, across all pages.
</ResponseField>

<ResponseField name="limit" type="integer" required>
  The page size applied, after clamping.
</ResponseField>

<ResponseField name="offset" type="integer" required>
  The offset applied, after clamping.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  `true` when more documents follow this page.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request GET "$MITHUNAI_URL/arukz/api/v1/knowledge/documents?collection_id=0b6f2c14-8a3d-4e91-9c77-2f5b1d0a4e88&limit=2&offset=0" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os, requests

  response = requests.get(
      f"{os.environ['MITHUNAI_URL']}/arukz/api/v1/knowledge/documents",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      params={
          "collection_id": "0b6f2c14-8a3d-4e91-9c77-2f5b1d0a4e88",
          "limit": 2,
          "offset": 0,
      },
      timeout=60,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({
    collection_id: '0b6f2c14-8a3d-4e91-9c77-2f5b1d0a4e88',
    limit: '2',
    offset: '0',
  })
  const response = await fetch(
    `${process.env.MITHUNAI_URL}/arukz/api/v1/knowledge/documents?${params}`,
    {
      headers: { Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}` },
    },
  )
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "data": [
      {
        "id": "7e2d4b1a-9c3f-5a86-b1e4-0d6c8f2a3b57",
        "collection_id": "0b6f2c14-8a3d-4e91-9c77-2f5b1d0a4e88",
        "source_id": "5d1e7a90-3c4b-4f2a-8e61-7b9c0d2f4a13",
        "title": "Rate limits",
        "path": "docs/api/rate-limits.md",
        "content_type": "markdown",
        "status": "active",
        "source_url": "https://github.com/example-org/platform-docs/blob/4f9c2e7a1b3d5c8e0f2a4b6c8d0e1f3a5b7c9d2e/docs/api/rate-limits.md",
        "source_version": "4f9c2e7a1b3d5c8e0f2a4b6c8d0e1f3a5b7c9d2e",
        "first_seen_at": "2026-09-24T10:21:13.550182",
        "last_seen_at": "2026-09-24T10:21:13.550182"
      },
      {
        "id": "1c8f3e6d-2a7b-5d90-8e14-b3f60a9c7d25",
        "collection_id": "0b6f2c14-8a3d-4e91-9c77-2f5b1d0a4e88",
        "source_id": "5d1e7a90-3c4b-4f2a-8e61-7b9c0d2f4a13",
        "title": "Authentication",
        "path": "docs/api/authentication.md",
        "content_type": "markdown",
        "status": "active",
        "source_url": "https://github.com/example-org/platform-docs/blob/4f9c2e7a1b3d5c8e0f2a4b6c8d0e1f3a5b7c9d2e/docs/api/authentication.md",
        "source_version": "4f9c2e7a1b3d5c8e0f2a4b6c8d0e1f3a5b7c9d2e",
        "first_seen_at": "2026-09-24T10:21:09.204771",
        "last_seen_at": "2026-09-24T10:21:09.204771"
      }
    ],
    "total": 198,
    "limit": 2,
    "offset": 0,
    "has_more": true
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "validation_error", "message": "'collection_id' is required." }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "not_found", "message": "The knowledge collection was not found." }
  ```
</ResponseExample>