Knowledge — Kraterion docs

Knowledge

Knowledge makes a bucket searchable. Once it's on, every object is chunked, embedded, and indexed so an agent — or a direct search call — can pull the right passages and cite them.

Enable knowledge

Toggle knowledge per bucket in the dashboard, or over the API with a bearer token. Enabling kicks off a backfill that indexes whatever is already in the bucket.

curl -X POST https://api.kraterion.com/v1/buckets/<bucket_id>/knowledge \
  -H "Authorization: Bearer kr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "embedding_model": "text-embedding-3-small",
    "chunk_tokens": 512,
    "chunk_overlap_tokens": 128
  }'

Fetch the current state — including a summary of how many objects are indexed, pending, failed, or skipped — with GET /v1/buckets/:id/knowledge.

Prerequisites

Embeddings are generated with your own OpenAI key, so the project needs an active OpenAI key configured before knowledge can be enabled. For a private bucket, the indexer also needs on-chain access to read the objects it's indexing — enabling knowledge surfaces whether that grant is required, and the dashboard walks you through it.

The indexing pipeline

When an object lands, the indexer decrypts it, splits it into overlapping chunks of chunk_tokens tokens (with chunk_overlap_tokens of overlap to preserve context across boundaries), embeds each chunk, and stores both the text and the vector. Overwriting an object re-indexes it; deleting it removes its chunks.

Manifests

Indexing produces a manifest per object: the ordered list of chunks, each chunk's content hash, and the Walrus blob ids the content came from. The manifest is what makes a citation checkable — a hash ties a quoted passage back to specific, content-addressed bytes. Agents can fetch it via the kraterion_get_manifest tool.

Backfill & reindex

Re-run indexing over the whole bucket with POST /v1/buckets/:id/knowledge/backfill. To change chunking or the embedding model, use POST /v1/buckets/:id/knowledge/reindex — it clears the existing chunks and rebuilds them with the new settings. Disable knowledge by posting { "enabled": false }.