List Knowledge Bases

List active knowledge bases in a workspace with folder filtering, search, sorting, and cursor pagination. Use scope=archived to find knowledge bases available for restoration. Workspace folder trees exceeding 10,000 folders return 413.

OAuth scope: api:read.

GET/api/v2/knowledge

Authorization

X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Query Parameters

workspaceId*string

Workspace whose knowledge bases should be listed.

Length1 <= length <= 128
scope?string

Lifecycle scope: active or archived knowledge bases. Use Restore Knowledge Base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.

Default"active"
Value in"active" | "archived"
folderPath?Folder path input

Restrict results to knowledge bases in this folder. Unknown folder paths contribute no matches.

Lengthlength <= 4096
search?string

Case-insensitive substring match against the resource name.

Length1 <= length <= 200
sortBy?string

Field used to sort the result. Sorting by name is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.

Default"createdAt"
Value in"name" | "createdAt" | "updatedAt"
sortOrder?string

Sort direction.

Default"asc"
Value in"asc" | "desc"
limit?integer

Maximum knowledge bases to return per page. Must be a whole number from 1 to 100. Defaults to 50.

Default50
Range1 <= value <= 100
cursor?string

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/knowledge?workspaceId=string" \  -H "X-API-Key: YOUR_API_KEY"
{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Product Documentation",
      "description": "All product documentation and guides",
      "tokenCount": 48213,
      "embeddingModel": "text-embedding-3-small",
      "embeddingDimension": 1536,
      "chunkingConfig": {
        "maxSize": 1024,
        "minSize": 100,
        "overlap": 200,
        "strategy": "auto",
        "strategyOptions": {
          "pattern": "string",
          "separators": [
            "string"
          ],
          "recipe": "plain",
          "strictBoundaries": true
        },
        "property1": null,
        "property2": null
      },
      "docCount": 12,
      "connectorTypes": [
        "notion",
        "google_drive"
      ],
      "createdAt": "2025-01-10T09:00:00Z",
      "updatedAt": "2025-06-18T16:45:00Z",
      "webUrl": "http://example.com",
      "ownerEmail": "owner@example.com",
      "folderPath": "/Product",
      "deletedAt": "2026-01-16T09:00:00Z"
    }
  ],
  "nextCursor": "string"
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
GETGet Next Tag SlotGETList Chunks