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

# List documents

> List Pharen Docs documents the API key can read, with optional team, collection, and search filters for inventories, indexing, and exports.

Returns Pharen Docs documents visible to the key creator. Use this endpoint for document inventories, search indexing jobs, and export tools.

<Note>
  Required API key scope: `docs:read`.
</Note>

## Query parameters

<ParamField query="team_id" type="string">
  Team UUID for team-scoped keys.
</ParamField>

<ParamField query="collection_id" type="string">
  Optional collection UUID to limit results to one collection.
</ParamField>

<ParamField query="search" type="string">
  Search term for document names and visible metadata.
</ParamField>

<ParamField query="page" type="integer">
  Page number for paginated responses.
</ParamField>

## Response

<ResponseField name="count" type="integer">
  Total number of matching documents.
</ResponseField>

<ResponseField name="results" type="array">
  Document records visible to the key.
</ResponseField>


## OpenAPI

````yaml openapi.json GET /api/kb/documents/
openapi: 3.1.0
info:
  title: Pharen Hub API
  version: 1.0.0
  description: >-
    Scoped REST API for Pharen Hub workspaces, calendars, lists, docs,
    workflows, and agents.
servers:
  - url: '{baseUrl}'
    description: Pharen Hub API base URL
    variables:
      baseUrl:
        default: https://pharen.app
        description: >-
          The Pharen Hub API origin. Keep the default for production, or enter
          another environment such as http://localhost:8000.
security:
  - bearerAuth: []
tags:
  - name: Calendar
    description: Calendar source and event operations.
  - name: Lists
    description: Saved list data and metadata operations.
  - name: Docs
    description: Document and collection operations.
  - name: Workflows
    description: Workflow definition and execution operations.
  - name: Agents
    description: Agent catalog and chat operations.
paths:
  /api/kb/documents/:
    get:
      tags:
        - Docs
      summary: List documents
      description: >-
        Fetch document and collection metadata available to the API key.
        Requires the `docs:read` scope.
      operationId: listDocuments
      parameters:
        - name: collection_id
          in: query
          description: Optional collection UUID to filter documents.
          schema:
            type: string
            format: uuid
        - name: team_id
          in: query
          description: Team UUID for team-scoped keys.
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number for paginated results.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Documents returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDocuments'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    PaginatedDocuments:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        collection_id:
          type: string
          format: uuid
        team_id:
          type: string
          format: uuid
        updated_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: forbidden
            message:
              type: string
              example: This API key does not have the required scope.
            details:
              type: object
              additionalProperties: true
  responses:
    Unauthorized:
      description: The request did not include a valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The API key is valid but does not have the required scope or workspace
        access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Paste your Pharen API key without the Bearer prefix.
      x-default: phk_your_api_key

````