Create a knowledge base

curl --request POST \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

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"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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
}

POST

knowledge_bases

Create a knowledge base

curl --request POST \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

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"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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
}

Authorizations

Authorization

string

header

required

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

Body

application/json

name

string

required

Maximum string length: 256

description

string

Maximum string length: 4096

provider

enum<string>

Defaults to the platform-configured provider. Not strictly server-validated - an unsupported value surfaces as a 500 from the vector router rather than a 400.

Available options:

mock,

elasticsearch,

opensearch,

redis,

pgvector,

qdrant,

pinecone

embedding

object

Defaults to the platform-configured embedding model.

Hide child attributes

embedding.model

string

embedding.dimensions

integer

Required range: x >= 1

chunking_strategy

object

parser

enum<string>

Available options:

tika,

tika-ocr,

unstructured,

unstructured-ocr,

llm

file_parsing

object

Hide child attributes

file_parsing.image

string

file_parsing.audio

string

file_parsing.document

string

agent_id

string

Binds the store to an agent (conversation scope).

expires_after

object

Optional expiry policy persisted on the store row (e.g. conversation-scoped stores).

Response

Knowledge base created (status creating until provisioned, then active).

Knowledge base metadata. PATCH is metadata-only; web-crawl configuration lives in /web_sources.

string

required

Maximum string length: 128

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

object

enum<string>

required

Available options:

knowledge_base

name

string

required

Maximum string length: 256

provider

enum<string>

required

Available options:

mock,

elasticsearch,

opensearch,

redis,

pgvector,

qdrant,

pinecone

index_name

string

required

Physical index name on the provider.

embedding

object

required

Hide child attributes

embedding.model

string

required

embedding.dimensions

integer

required

Required range: x >= 1

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

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

owner.type

enum<string>

required

Available options:

user,

agent,

org

owner.id

string

required

Maximum string length: 128

owner_org_slug

string

required

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

created_at

integer

required

description

string

Maximum string length: 4096

chunking_strategy

object

Default chunking for documents; overridable per document.

parser

enum<string> | null

Available options:

tika,

tika-ocr,

unstructured,

unstructured-ocr,

llm,

null

file_parsing

object | null

Hide child attributes

file_parsing.image

string

file_parsing.audio

string

file_parsing.document

string

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

document_counts.queued

integer

Required range: x >= 0

document_counts.in_progress

integer

Required range: x >= 0

document_counts.completed

integer

Required range: x >= 0

document_counts.failed

integer

Required range: x >= 0

document_counts.fetch_expired

integer

Required range: x >= 0

document_counts.total

integer

Required range: x >= 0

owner_user_id

string | null

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

agent_id

string | null

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

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

access_reason

enum<string> | null

Available options:

owner,

admin_binding,

editor_binding,

reader_binding,

agent_binding,

trusted_workspace,

null

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

processing.status

enum<string> | null

Available options:

idle,

processing,

paused,

unknown,

null

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.

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

processing.health.status

enum<string>

Available options:

HEALTHY,

OUT_OF_SPACE,

PAUSED,

UNAUTHENTICATED,

UNHEALTHY

processing.health.message

string | null

processing.health.last_event_at

integer | null

processing.metrics

object | null

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

Hide child attributes

processing.metrics.total_items

integer

Required range: x >= 0

processing.metrics.indexed

integer

Required range: x >= 0

processing.metrics.failed

integer

Required range: x >= 0

processing.metrics.skipped

integer

Required range: x >= 0

processing.last_run_at

integer | null

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

crawl_settings.webpages_limit

integer | null

required

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

Required range: x >= 1

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).

crawl_settings.paused

boolean

required

Whether the whole crawler is paused.

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).

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

last_active_at

integer | null

Unix seconds.

updated_at

integer

List knowledge bases visible to the caller Retrieve a knowledge base

⌘I

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Create a knowledge base

Authorizations

Body

Response