Quickstart

An admin creates it. The handle is what every request, key scope and tool argument names, so it is lowercase, dash-separated and permanent; the display name is the part you can change later.

curl -X POST https://api.vatan.one/api/orgs/$ORG/knowledge \
  -H "content-type: application/json" --cookie "$SESSION" \
  -d '{"name":"Employee handbook","handle":"handbook"}'

Two steps, because the file goes straight to object storage and never through the API. Ask for an upload URL, PUT the bytes to it, then register what you uploaded.

# 1. ask
curl -X POST https://api.vatan.one/api/orgs/$ORG/knowledge/$BASE/uploads \
  -H "content-type: application/json" --cookie "$SESSION" \
  -d '{"filename":"handbook.pdf","contentType":"application/pdf","contentLength":402118}'

# 2. PUT the file to the returned url, with the returned headers

# 3. register it
curl -X POST https://api.vatan.one/api/orgs/$ORG/knowledge/$BASE/documents \
  -H "content-type: application/json" --cookie "$SESSION" \
  -d '{"key":"knowledge/...","filename":"handbook.pdf","contentType":"application/pdf","checksum":"<sha256>"}'

Registering answers 202: indexing is a background job. Watch the document's status in the console. Plaintext, Markdown, HTML and PDFs with a text layer are supported; anything else is refused with a reason rather than indexed badly.

A key reads nothing until it is scoped. That is deliberate and is the opposite of how the MCP bundle scope narrows: there is no sensible default knowledge base, and inventing one would mean a key made for a support bot silently reading HR.

curl -X PUT https://api.vatan.one/api/orgs/$ORG/gateway/keys/$KEY/knowledge \
  -H "content-type: application/json" --cookie "$SESSION" \
  -d '{"baseIds":["'$BASE'"]}'

One header on a call you already make.

curl https://api.vatan.one/v1/chat/completions \
  -H "authorization: Bearer $VATAN_API_KEY" \
  -H "x-vatan-knowledge: handbook" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"How much parental leave do I get?"}]}'

The response carries x-vatan-knowledge-chunks, so you can tell an answer that was grounded from one that was not. Zero chunks means retrieval ran and found nothing, which is a different thing from the header being ignored.