---
title: "List Knowledge Files"
method: GET
path: "/v1/knowledge-files"
tags: ["Agent Knowledge Files"]
---

# List Knowledge Files

`GET /v1/knowledge-files`

## Request

- Base URL: `https://api.bey.dev`
- URL: `https://api.bey.dev/v1/knowledge-files`
- Auth: API key in header `x-api-key`

List your knowledge files.

Returns a cursor-paginated list of the knowledge files you own, along with
their processing status.

## Query parameters

- `limit` integer: Maximum number of objects to return.
- `cursor` string, nullable: Cursor for pagination.

## Response `200`

Paginated List of Knowledge Files

- union
  - HasMorePageKnowledgeFileResponse
    - `data` KnowledgeFileResponse[], required: List of objects.
      - union
        - ToUploadKnowledgeFileResponse: Response model for a knowledge file that is to be uploaded.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'to-upload'
        - ProcessingKnowledgeFileResponse: Response model for a knowledge file that is still being processed.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'processing'
        - AvailableKnowledgeFileResponse: Response model for an available knowledge file.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'available'
          - `text` string, required: Text extracted from the file. Shortened to the start of the file when it is a large one; see `is_text_complete`.
          - `is_text_complete` boolean, required: Whether `text` is the whole file rather than the start of it. A large file is stored and searched in full either way; this only says how much of it this endpoint hands back.
        - FailedKnowledgeFileResponse: Response model for a knowledge file that could not be processed.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'failed'
          - `reason` string, required
    - `has_more` true: Whether there are more objects to fetch.
    - `next_cursor` string, required: The cursor for the next page of objects.
  - NoMorePageKnowledgeFileResponse
    - `data` KnowledgeFileResponse[], required: List of objects.
      - union
        - ToUploadKnowledgeFileResponse: Response model for a knowledge file that is to be uploaded.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'to-upload'
        - ProcessingKnowledgeFileResponse: Response model for a knowledge file that is still being processed.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'processing'
        - AvailableKnowledgeFileResponse: Response model for an available knowledge file.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'available'
          - `text` string, required: Text extracted from the file. Shortened to the start of the file when it is a large one; see `is_text_complete`.
          - `is_text_complete` boolean, required: Whether `text` is the whole file rather than the start of it. A large file is stored and searched in full either way; this only says how much of it this endpoint hands back.
        - FailedKnowledgeFileResponse: Response model for a knowledge file that could not be processed.
          - `id` string, required: Unique identifier of the object in the database.
          - `name` string, required
          - `format` 'text' | 'pdf', required: Format of the knowledge file.
          - `status` 'failed'
          - `reason` string, required
    - `has_more` false: Whether there are more objects to fetch.

## Other responses

- `401`: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
- `402`: The plan's usage limit has been reached, or the requested feature requires a plan upgrade.
- `403`: The API key is valid but not permitted to perform this action, because the resource belongs to someone else.
- `404`: The requested resource does not exist or is not accessible with this API key.
- `422`: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
- `429`: The plan's limit on the number of concurrent sessions has been reached.

## Changes

- **2026-10-20** `0469e200c235`: 1 info
  - added the non-success response with the status `402`
- **2026-10-16** `c8f80740b51c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bey-dev/apis/beyond-presence-api/changes/v1/knowledge-files/get.md)

---

[API](https://skmtc.dev/bey-dev/apis/beyond-presence-api.md) - [All operations](https://skmtc.dev/bey-dev/apis/beyond-presence-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bey-dev/apis/beyond-presence-api/revisions/2d37d86bc5c1?raw)