Kognita
All posts
Tutorial2026-07-20·9 min read

Kognita API walkthrough: create a knowledge base, add content, run search

A complete end-to-end tour of the Kognita REST API — from an empty account to answering questions over your content — in about a dozen requests.

This is the full path from nothing to a working search API over your own content, using only HTTP requests. No SDK required — every step is a plain REST call you can run from curl, your language of choice, or Postman. By the end you'll have a knowledge base, ingested content, and both semantic and hybrid search returning grounded results.

Kognita API walkthrough

Prerequisites

You need two things from your Kognita dashboard:

  • An API key — sent as the X-API-Key header.
  • Your Organization ID — sent as the X-Organization-Id header.

Every request below carries both. We'll set them once:

export KOGNITA_API_KEY="sk_..."
export KOGNITA_ORG_ID="org_..."
export BASE="https://api.kognita.dev/v1"

Step 1: Create a knowledge base

A knowledge base is the container for related content. Create one and note the id it returns — everything else hangs off it.

curl -X POST "$BASE/knowledge-bases" \
  -H "X-API-Key: $KOGNITA_API_KEY" \
  -H "X-Organization-Id: $KOGNITA_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs",
    "description": "Public product documentation and guides"
  }'

{ "id": "kb_a1b2c3d4e5f6g7h8", "name": "Product Docs", "created_at": "2026-07-20T10:00:00Z" }

Each knowledge base has a configuration — embedding model, chunking strategy, vector type — with sensible defaults applied automatically. You can override them at creation time, but the defaults (recursive-style token chunking, a strong general-purpose embedding model) are a good starting point for most content.

Step 2: Add content

Post your documents to the knowledge base. Kognita handles chunking, embedding, and vector storage asynchronously — you send text, it does the pipeline.

curl -X POST "$BASE/knowledge-bases/kb_a1b2c3d4e5f6g7h8/content" \
  -H "X-API-Key: $KOGNITA_API_KEY" \
  -H "X-Organization-Id: $KOGNITA_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "VPN Setup Guide",
    "body": "To connect to the corporate VPN on macOS, open System Settings > Network..."
  }'

{ "id": "cnt_9z8y7x6w5v4u3t2s", "status": "PROCESSING" }

Note the status: PROCESSING. Ingestion is a background job: the content is queued, chunked, embedded, and written to the vector store. It doesn't block your request. Repeat this call for each document you want to add.

Step 3: Check ingestion status

Because ingestion is async, poll the content until it's READY before you expect it in search results.

curl "$BASE/knowledge-bases/kb_a1b2c3d4e5f6g7h8/content/cnt_9z8y7x6w5v4u3t2s" \
  -H "X-API-Key: $KOGNITA_API_KEY" \
  -H "X-Organization-Id: $KOGNITA_ORG_ID"

{ "id": "cnt_9z8y7x6w5v4u3t2s", "title": "VPN Setup Guide", "status": "READY" }

READY means the content is chunked, embedded, and searchable. If something failed upstream, you'll see an error status rather than a silent gap — ingestion is designed to surface failures, not swallow them.

Step 4: Run a semantic search

Now the payoff. Semantic search embeds your query and finds the nearest chunks by meaning — no keyword overlap required.

curl -X POST "$BASE/knowledge-bases/kb_a1b2c3d4e5f6g7h8/search/semantic" \
  -H "X-API-Key: $KOGNITA_API_KEY" \
  -H "X-Organization-Id: $KOGNITA_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how do I get on the company network remotely?", "limit": 3 }'

{
  "results": [
    {
      "content": "To connect to the corporate VPN on macOS, open System Settings > Network...",
      "source": "VPN Setup Guide",
      "score": 0.89
    }
  ]
}

Notice the query — "get on the company network remotely" — shares almost no words with the document, which talks about "VPN" and "System Settings." Semantic search bridges that gap. Keyword search would have returned nothing.

Step 5: Run a hybrid search

For production, prefer hybrid search. It fuses semantic retrieval with keyword (BM25) matching and reranks the combined results, so exact terms — product names, error codes, API methods — aren't lost to semantic drift.

curl -X POST "$BASE/knowledge-bases/kb_a1b2c3d4e5f6g7h8/search/hybrid" \
  -H "X-API-Key: $KOGNITA_API_KEY" \
  -H "X-Organization-Id: $KOGNITA_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "query": "VPN setup macOS", "limit": 3 }'

Hybrid is the recommended default for most applications: it keeps the meaning-matching strength of vectors while making sure a query full of exact keywords still hits the passages that contain those exact keywords.

Step 6: From search to answers

Search returns passages. To turn them into a written answer, hand the top results to an LLM as grounding context — retrieve with the call above, then prompt the model to answer only from those passages and cite them. That's the whole RAG loop, and it's the same pattern whether you build it yourself or let an MCP-compatible assistant call the search tool directly.

What you've built

In roughly a dozen requests you went from an empty account to a working retrieval API over your own content:

  1. Created a knowledge base
  2. Added content (chunked and embedded for you)
  3. Waited for async ingestion to reach READY
  4. Searched semantically and via hybrid retrieval

Everything else in the API — connectors that sync from Notion or Drive, metadata filtering to scope retrieval, the MCP server that exposes all of this as a tool — builds on these same primitives. Master the create-content-search loop and the rest is composition.