HTML docs · raw markdown

Kobold public API wiki

This wiki explains how to use the Insula Labs public API and the kobold-cli tool. It covers what you can do, how each operation behaves, and how the pieces fit together.

Base URL: https://api.insulalabs.io

CLI: kobold-cli (ships with the web-api project; defaults to the base URL above)

What you can do

With an API key you can:

Create and manage knowledgebases (private document collections)
Upload and organize files inside a knowledgebase
Ask the platform to index those files
Run semantic search over the index
Read file bytes when you need more than a search snippet
List site agents and arm schedules (fixed interval presets + optional webhook hooks)

One-shot jobs, job event streams, and admin/provider surfaces are not part of this API.

Mental model

create knowledgebase
        │
        ▼
   upload files  ──►  sync index  ──►  search
        │                                  │
        └──────── read file content ◄──────┘

A knowledgebase has a stable id like kb_7k2m9x4q and a display name you can rename.
Files live under that knowledgebase in a folder tree. Paths are relative (for example docs/guide.md).
Search uses the index, not the live tree alone. After you change files, sync (and wait until the index is ready) before expecting new content in search results.
Search returns locations (and optional short snippets). Full file bodies come from the content endpoint.

Pages

Page	Contents
Getting started	API key, env vars, build the CLI, smoke tests
CLI reference	Every `kobold-cli` section, action, and flag
Knowledgebases	Create, list, get, update, delete
Files	Tree, mkdir, ingest, rename, delete, content
Index and search	Status, sync, sparse vs full search
Errors	Status codes and rate-limit response headers

Typical session

export KOBOLD_API_KEY='your-key-here'

kobold-cli health check
kobold-cli kb create -name notes -description "project notes"
kobold-cli kb list

# use the id from create/list, e.g. kb_qc0rp0gz
kobold-cli files mkdir -kb kb_qc0rp0gz -path docs
kobold-cli files ingest -kb kb_qc0rp0gz -filename guide.md -dest-dir docs -file ./guide.md
kobold-cli index sync -kb kb_qc0rp0gz
kobold-cli index status -kb kb_qc0rp0gz

kobold-cli search query -kb kb_qc0rp0gz -query "how do I get started" -mode sparse
kobold-cli search query -kb kb_qc0rp0gz -query "how do I get started" -mode full

When search hits point at a path, fetch more bytes with:

kobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md -out ./guide.md

Conventions

Authenticated routes expect Authorization: Bearer <api_key>.
JSON uses camelCase. Timestamps are RFC 3339.
Knowledgebase ids in paths and CLI flags are the kb_… values returned by create/list.
Unknown knowledgebase ids (including ones that are not yours) return 404.