List knowledge bases visible to the caller

curl --request GET \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "object": "list",
  "data": [
    {
      "id": "<string>",
      "object": "knowledge_base",
      "name": "<string>",
      "index_name": "<string>",
      "embedding": {
        "model": "<string>",
        "dimensions": 2
      },
      "owner": {
        "id": "<string>"
      },
      "owner_org_slug": "<string>",
      "created_at": 123,
      "description": "<string>",
      "chunking_strategy": {},
      "file_parsing": {
        "image": "<string>",
        "audio": "<string>",
        "document": "<string>"
      },
      "document_counts": {
        "queued": 1,
        "in_progress": 1,
        "completed": 1,
        "failed": 1,
        "fetch_expired": 1,
        "total": 1
      },
      "owner_user_id": "<string>",
      "agent_id": "<string>",
      "processing": {
        "crawler_reachable": true,
        "health": {
          "message": "<string>",
          "last_event_at": 123
        },
        "metrics": {
          "total_items": 1,
          "indexed": 1,
          "failed": 1,
          "skipped": 1
        },
        "last_run_at": 123
      },
      "crawl_settings": {
        "webpages_limit": 2,
        "periodicity": 123,
        "paused": true,
        "max_webpages_limit": 123
      },
      "web_source_count": 1,
      "last_active_at": 123,
      "updated_at": 123
    }
  ],
  "total": 1,
  "page": 2,
  "limit": 50,
  "has_more": true
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authentication required."
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "details": {}
  }
}

GET

knowledge_bases

List knowledge bases visible to the caller

curl --request GET \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "object": "list",
  "data": [
    {
      "id": "<string>",
      "object": "knowledge_base",
      "name": "<string>",
      "index_name": "<string>",
      "embedding": {
        "model": "<string>",
        "dimensions": 2
      },
      "owner": {
        "id": "<string>"
      },
      "owner_org_slug": "<string>",
      "created_at": 123,
      "description": "<string>",
      "chunking_strategy": {},
      "file_parsing": {
        "image": "<string>",
        "audio": "<string>",
        "document": "<string>"
      },
      "document_counts": {
        "queued": 1,
        "in_progress": 1,
        "completed": 1,
        "failed": 1,
        "fetch_expired": 1,
        "total": 1
      },
      "owner_user_id": "<string>",
      "agent_id": "<string>",
      "processing": {
        "crawler_reachable": true,
        "health": {
          "message": "<string>",
          "last_event_at": 123
        },
        "metrics": {
          "total_items": 1,
          "indexed": 1,
          "failed": 1,
          "skipped": 1
        },
        "last_run_at": 123
      },
      "crawl_settings": {
        "webpages_limit": 2,
        "periodicity": 123,
        "paused": true,
        "max_webpages_limit": 123
      },
      "web_source_count": 1,
      "last_active_at": 123,
      "updated_at": 123
    }
  ],
  "total": 1,
  "page": 2,
  "limit": 50,
  "has_more": true
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authentication required."
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.

Query Parameters

limit

integer

default:20

Page size. Server clamps to [1, 100] silently.

Required range: 1 <= x <= 100

page

integer

default:1

1-based page number.

Required range: x >= 1

name

string

Case-insensitive substring match on name.

string

Case-insensitive substring match on name OR description (legacy /vector_stores?search= parity; takes precedence over name when both are sent - added 2026-07-15, SPA migration F1).

agent_id

string

scope

string

Comma-separated list of store populations to include - owned, shared, all, agents. Defaults to owned,shared. all/agents require the corresponding admin/agent access.

status

enum<string>

Documented valid values; not strictly server-validated - an unrecognized value yields an empty result rather than a 400.

Available options:

creating,

active,

failed,

deleting

Response

Paginated knowledge bases.

Shared list-response envelope. Array is always data. Every element carries its own object discriminator.

object

enum<string>

required

Available options:

list

data

object[]

required

Hide child attributes

data.id

string

required

Maximum string length: 128

Pattern: ^vs_[A-Za-z0-9-]+$

data.object

enum<string>

required

Available options:

knowledge_base

data.name

string

required

Maximum string length: 256

data.provider

enum<string>

required

Available options:

mock,

elasticsearch,

opensearch,

redis,

pgvector,

qdrant,

pinecone

data.index_name

string

required

Physical index name on the provider.

data.embedding

object

required

Hide child attributes

data.embedding.model

string

required

data.embedding.dimensions

integer

required

Required range: x >= 1

data.status

enum<string>

required

creating before external resources are provisioned; active after metadata + physical setup + owner binding succeed; failed is a visible failed state with a cleanup-job hook; deleting is the transactional deletion window.

Available options:

creating,

active,

failed,

deleting

data.owner

object

required

First-class owner principal (§F-6). For agent-owned (conversation-scope) stores type: agent and id is the agent id - represented as a principalType: agent binding in the platform-managed product_bindings store, NOT a blanked owner_user_id. owner_user_id / agent_id below mirror this for convenience and filtering.

Hide child attributes

data.owner.type

enum<string>

required

Available options:

user,

agent,

org

data.owner.id

string

required

Maximum string length: 128

data.owner_org_slug

string

required

Tenant scope. All knowledge-base lookups are scoped by this field.

data.created_at

integer

required

data.description

string

Maximum string length: 4096

data.chunking_strategy

object

Default chunking for documents; overridable per document.

data.parser

enum<string> | null

Available options:

tika,

tika-ocr,

unstructured,

unstructured-ocr,

llm,

null

data.file_parsing

object | null

Hide child attributes

data.file_parsing.image

string

data.file_parsing.audio

string

data.file_parsing.document

string

data.document_counts

object

Per-status aggregate over this store's documents. Maintained with transitions guarded by each document's index_generation - duplicate or stale crawler callbacks cannot corrupt counters.

Hide child attributes

data.document_counts.queued

integer

Required range: x >= 0

data.document_counts.in_progress

integer

Required range: x >= 0

data.document_counts.completed

integer

Required range: x >= 0

data.document_counts.failed

integer

Required range: x >= 0

data.document_counts.fetch_expired

integer

Required range: x >= 0

data.document_counts.total

integer

Required range: x >= 0

data.owner_user_id

string | null

owner.id when owner.type == user; null for agent-owned stores.

data.agent_id

string | null

owner.id when owner.type == agent; null otherwise. Filterable on list.

data.role

enum<string> | null

Caller's effective role, computed at read time from access bindings. Null on cross-workspace (workspace_jwt) reads.

Available options:

owner,

admin,

editor,

reader,

null

data.access_reason

enum<string> | null

Available options:

owner,

admin_binding,

editor_binding,

reader_binding,

agent_binding,

trusted_workspace,

null

data.processing

object

Knowledge-base processing / parser-backend health (§F-5). The crawler is the universal parse/fetch backend for EVERY document (uploads, single pages, web crawl), so this is present whenever the knowledge base has documents - even with zero web sources. Live fields come from the crawler; when it is unreachable crawler_reachable is false and the live status/metrics degrade to null rather than erroring (replacing the legacy overloaded status:"unknown" + crawler_error). DB-derived per-seed counts live on /web_sources and remain available regardless.

Hide child attributes

data.processing.status

enum<string> | null

Available options:

idle,

processing,

paused,

unknown,

null

data.processing.crawler_reachable

boolean | null

null by default - the live crawler round-trip only runs when the KB detail request passes ?include=processing; true/ false otherwise.

data.processing.health

object

The persisted crawler health - previously exposed by no endpoint, now surfaced here (powers OUT_OF_SPACE / PAUSED inline banners).

Hide child attributes

data.processing.health.status

enum<string>

Available options:

HEALTHY,

OUT_OF_SPACE,

PAUSED,

UNAUTHENTICATED,

UNHEALTHY

data.processing.health.message

string | null

data.processing.health.last_event_at

integer | null

data.processing.metrics

object | null

Live KB-wide item counts from the crawler; null when unreachable.

Hide child attributes

data.processing.metrics.total_items

integer

Required range: x >= 0

data.processing.metrics.indexed

integer

Required range: x >= 0

data.processing.metrics.failed

integer

Required range: x >= 0

data.processing.metrics.skipped

integer

Required range: x >= 0

data.processing.last_run_at

integer | null

data.crawl_settings

object

Engine-global crawl settings - one Crawler instance per KB, so these are the single values the crawler honors (they are NOT per-seed). Read from the store-level columns; edited via the KB PATCH (added 2026-07-17, web-sources crawl-settings re-home).

Hide child attributes

data.crawl_settings.webpages_limit

integer | null

required

Per-crawl page cap, governance-capped (Platform → Org hierarchy).

Required range: x >= 1

data.crawl_settings.periodicity

integer | null

required

Seconds between crawls; null = manual-only (seconds integer rather than an enum for lossless crawler parity - deviation 06-A-1).

data.crawl_settings.paused

boolean

required

Whether the whole crawler is paused.

data.crawl_settings.max_webpages_limit

integer | null

read-only

Resolved governance cap (Platform → Org hierarchy) for webpages_limit - the "max allowed" hint surfaced on the KB detail response. Read-only; not accepted on PATCH (added 2026-07-20).

data.web_source_count

integer

Number of registered web sources (crawl seeds). Summary metadata for list cards - the seed objects themselves stay on /web_sources (added 2026-07-15, SPA migration F1).

Required range: x >= 0

data.last_active_at

integer | null

Unix seconds.

data.updated_at

integer

total

integer

required

Required range: x >= 0

page

integer

required

Required range: x >= 1

limit

integer

required

Required range: 1 <= x <= 100

has_more

boolean

required

List audit events for an organization Create a knowledge base

⌘I

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

List knowledge bases visible to the caller

Authorizations

Query Parameters

Response