INSULA LABS

HTML docs · raw markdown

Knowledgebases

A knowledgebase is a private collection of files you can index and search. You never pass an owner id: every call runs as the account behind your API key.

Identifiers

Field Role
id Stable handle (kb_…). Use this in all nested routes and CLI -kb / -id flags.
name Display name. You can rename it; the id does not change.
description Short blurb.

Example object:

{
  "id": "kb_qc0rp0gz",
  "name": "notes",
  "description": "project notes",
  "status": "complete",
  "statusInfo": "index up to date",
  "createdAt": "2026-07-15T13:24:19.812169Z",
  "lastUpdated": "2026-07-15T13:53:38.853622Z"
}

status / statusInfo reflect indexing progress for this knowledgebase. Common status values: pending, checking, digesting, halted, error, complete.

List

kobold-cli kb list
kobold-cli kb list -offset 0 -limit 20

GET /v1/knowledgebases?offset=0&limit=50
Authorization: Bearer <api_key>
Query Default Notes
offset 0 Skip this many rows
limit 50 Max 100

Results are ordered newest-first by createdAt. Response: JSON array of knowledgebase objects.

Create

kobold-cli kb create -name notes -description "project notes"

POST /v1/knowledgebases
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "name": "notes",
  "description": "project notes"
}

Both name and description are required. Response includes the new id. Initial index status is typically pending.

If you are at your plan’s knowledgebase count ceiling, create fails with 403.

Get

kobold-cli kb get -id kb_qc0rp0gz

GET /v1/knowledgebases/kb_qc0rp0gz
Authorization: Bearer <api_key>

Unknown or inaccessible ids → 404.

Patch

Update name and/or description. At least one field required.

kobold-cli kb patch -id kb_qc0rp0gz -name "project notes"
kobold-cli kb patch -id kb_qc0rp0gz -description "updated"

PATCH /v1/knowledgebases/kb_qc0rp0gz
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "name": "project notes"
}

Renaming does not change id or break existing file/search URLs that use that id.

Delete

kobold-cli kb delete -id kb_qc0rp0gz

DELETE /v1/knowledgebases/kb_qc0rp0gz
Authorization: Bearer <api_key>

Deletes the knowledgebase and its files. CLI prints {"ok": true} on success.

Related