List Knowledge bases

List Knowledge bases a workspace API key can already use

Lists Knowledge bases the API key can already use. Use this endpoint to discover ids, names, roles, and file counts before you upload, search, or manage access.

Before You Start

API key scope: Requires an API key with the KNOWLEDGE_FOLDER_API scope. Only workspace API keys receive Knowledge bases in this list. Personal keys return an empty list. See Share Knowledge bases with the API for setup instructions.
Knowledge bases: The Knowledge Folder API manages resources that appear as Knowledge bases in the Library.

Base URL

https://api.ajan.io

Request Format

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of Knowledge bases to return. Default: `50`. Minimum: `1`. Maximum: `100`.
`cursor`	string	No	UUID of the last Knowledge base from the previous page.

This endpoint lists Knowledge bases, not files. To list files inside one Knowledge base, use Retrieve Files.

Examples

List Knowledge bases with cURL

bash

curl -X GET "https://api.ajan.io/knowledge?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Knowledge bases with JavaScript

javascript

const axios = require("axios");

async function listKnowledgeBases(cursor) {
  const response = await axios.get("https://api.ajan.io/knowledge", {
    params: {
      limit: 50,
      cursor,
    },
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  });

  return response.data;
}

const firstPage = await listKnowledgeBases();
console.log(`Found ${firstPage.result.folders.length} Knowledge bases`);

firstPage.result.folders.forEach((folder) => {
  console.log(`- ${folder.name} (${folder.role}, ${folder.fileCount} files)`);
});

Response Format

Success Response (200 OK)

typescript

{
  status: "success";
  result: {
    folders: Array<{
      id: string;                 // Knowledge base ID
      name: string;               // Knowledge base name
      description: string | null; // Knowledge base description
      createdAt: string;          // ISO 8601 timestamp
      updatedAt: string;          // ISO 8601 timestamp
      fileCount: number;          // Non-deleted files in the Knowledge base
      role: "USER" | "EDITOR";    // This key's role. USER is Viewer.
    }>;
    nextCursor?: string;          // Present when another page remains
  };
}

role is EDITOR when the key has an explicit Editor grant. It is USER when the key has an explicit Viewer grant, or when the Knowledge base allows API search without an explicit key grant.

Results are ordered by createdAt descending, then id descending.

Example Response

json

{
  "status": "success",
  "result": {
    "folders": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Product handbook",
        "description": "Internal product documentation",
        "createdAt": "2026-08-12T09:15:00.000Z",
        "updatedAt": "2026-08-28T14:02:00.000Z",
        "fileCount": 12,
        "role": "EDITOR"
      },
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Support articles",
        "description": null,
        "createdAt": "2026-07-03T11:00:00.000Z",
        "updatedAt": "2026-08-01T16:40:00.000Z",
        "fileCount": 48,
        "role": "USER"
      }
    ],
    "nextCursor": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }
}

Error Handling

Status	Meaning
`400`	Invalid `limit` or `cursor`
`401`	Invalid or missing API key
`403`	Missing `KNOWLEDGE_FOLDER_API` scope
`429`	Rate limit exceeded
`500`	Unexpected server error

An unknown cursor returns 400 with "Invalid cursor".

There is no public endpoint to create or delete a Knowledge base.

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /knowledge:
    get:
      summary: List Knowledge bases accessible to the API key
      parameters:
        - name: limit
          in: query
          required: false
          description: Number of Knowledge bases to return. Default 50. Maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          description: UUID of the last Knowledge base from the previous page
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Knowledge bases retrieved successfully
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"