{"slug":"index","title":"Kobold public API wiki","path":"index.md","markdown":"# Kobold public API wiki\n\nThis 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.\n\n**Base URL:** `https://api.insulalabs.io`\n\n**CLI:** `kobold-cli` (ships with the web-api project; defaults to the base URL above)\n\n## What you can do\n\nWith an API key you can:\n\n1. Create and manage **knowledgebases** (private document collections)\n2. Upload and organize **files** inside a knowledgebase\n3. Ask the platform to **index** those files\n4. Run **semantic search** over the index\n5. Read file bytes when you need more than a search snippet\n6. List site **agents** and arm **schedules** (fixed interval presets + optional webhook hooks)\n\nOne-shot jobs, job event streams, and admin/provider surfaces are not part of this API.\n\n## Mental model\n\n```\ncreate knowledgebase\n        │\n        ▼\n   upload files  ──►  sync index  ──►  search\n        │                                  │\n        └──────── read file content ◄──────┘\n```\n\n- A **knowledgebase** has a stable `id` like `kb_7k2m9x4q` and a display `name` you can rename.\n- **Files** live under that knowledgebase in a folder tree. Paths are relative (for example `docs/guide.md`).\n- **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.\n- Search returns locations (and optional short snippets). Full file bodies come from the content endpoint.\n\n## Pages\n\n| Page | Contents |\n| ---- | -------- |\n| [Getting started](getting-started.md) | API key, env vars, build the CLI, smoke tests |\n| [CLI reference](cli-reference.md) | Every `kobold-cli` section, action, and flag |\n| [Knowledgebases](knowledgebases.md) | Create, list, get, update, delete |\n| [Files](files.md) | Tree, mkdir, ingest, rename, delete, content |\n| [Index and search](index-and-search.md) | Status, sync, sparse vs full search |\n| [Errors](errors.md) | Status codes and rate-limit response headers |\n\n## Typical session\n\n```bash\nexport KOBOLD_API_KEY='your-key-here'\n\nkobold-cli health check\nkobold-cli kb create -name notes -description \"project notes\"\nkobold-cli kb list\n\n# use the id from create/list, e.g. kb_qc0rp0gz\nkobold-cli files mkdir -kb kb_qc0rp0gz -path docs\nkobold-cli files ingest -kb kb_qc0rp0gz -filename guide.md -dest-dir docs -file ./guide.md\nkobold-cli index sync -kb kb_qc0rp0gz\nkobold-cli index status -kb kb_qc0rp0gz\n\nkobold-cli search query -kb kb_qc0rp0gz -query \"how do I get started\" -mode sparse\nkobold-cli search query -kb kb_qc0rp0gz -query \"how do I get started\" -mode full\n```\n\nWhen search hits point at a path, fetch more bytes with:\n\n```bash\nkobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md -out ./guide.md\n```\n\n## Conventions\n\n- Authenticated routes expect `Authorization: Bearer \u003capi_key\u003e`.\n- JSON uses camelCase. Timestamps are RFC 3339.\n- Knowledgebase ids in paths and CLI flags are the `kb_…` values returned by create/list.\n- Unknown knowledgebase ids (including ones that are not yours) return `404`.\n"}