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/context \
  -H "content-type: application/json" --cookie "$SESSION" \
  -d '{"name":"Employee handbook","handle":"handbook"}'

# The response carries the collection's id. Every URL below is addressed by id,
# so keep it:
#   { "id": "clx...", "name": "Employee handbook", "handle": "handbook", ... }
COLLECTION=clx...

The id and the handle are different things and both appear below. A URL path and a key scope name the id; the x-vatan-context header and an MCP tool argument name the handle. Naming one where the other belongs answers 404, the same refusal as a collection you may not read.

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/context/$COLLECTION/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/context/$COLLECTION/documents \
  -H "content-type: application/json" --cookie "$SESSION" \
  -d '{"key":"context/...","filename":"handbook.pdf","contentType":"application/pdf","checksum":"<sha256>"}'

Registering answers 202: indexing is a background job. The document appears in the console at queued and moves to ready or failed; the page does not refresh itself yet, so reload it to see where it got to. Plaintext, Markdown, HTML and PDFs with a text layer are supported, up to 25MB; 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 context collection, 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/context \
  -H "content-type: application/json" --cookie "$SESSION" \
  -d '{"collectionIds":["'$COLLECTION'"]}'

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-context: handbook" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"How much parental leave do I get?"}]}'

The response carries x-vatan-context-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.