Admin API

Everything the dashboard can do is a JSON REST call — the dashboard is just a client of this API. Use it for scripted setup, scheduled re-indexing, or monitoring.

Base URL http://localhost:3444/api

Authentication

Every request carries one of three credentials:

export API=http://localhost:3444/api
export TOKEN=your-admin-token
curl -s $API/projects -H "Authorization: Bearer $TOKEN" | jq

Five things follow from that split:

• What you may do depends on who you are. A session is bound to an account, so its instance role and its per-project memberships decide every call — see Accounts and Permissions. ADMIN_TOKEN always acts as root.
• An API token can never do more than the account that minted it. Its scope is checked after that account’s own role and membership, so narrowing it — to one project, or to a handful of routes — can only take authority away, never add it.
• A cookie request that changes something must come from this site. The server checks Sec-Fetch-Site, falling back to Origin and Referer, and answers 403 csrf_blocked otherwise. Bearer requests are exempt: they carry no ambient credential, which is why curl and CI — sending neither header — work unchanged.
• Neither bearer token counts as a signed-in account, as far as these routes are concerned. The endpoints that are about your account (/api/auth/password, /api/auth/sessions) require a session — that check refuses ADMIN_TOKEN and a scoped API token alike with 403 token_has_no_account, even a token scoped to allow the exact route. Only a browser holding a session cookie can reach them.
• A project you cannot reach answers 404, not 403, the same as a project that does not exist, so ids cannot be probed. A route you may reach but not use in that way answers 403.

GET /api/health, GET /api/setup/status, POST /api/setup, POST /api/auth/login, GET /api/auth/oidc/login and GET /api/auth/oidc/callback are the only endpoints reachable with no credential at all — the last two because the browser has no session yet when it asks for the redirect, and the provider sends the browser back to the callback with the code, by redirect — not a server-to-server call from the provider itself. Linking an already signed-in account to that same provider (POST /api/auth/oidc/link, DELETE /api/auth/oidc/link — see Single Sign-On) is different: it needs the caller’s own session, same as any other self-service account endpoint.

---

Health

curl -s $API/health | jq

{
  "ok": true,
  "version": "0.2.0",
  "uptimeSec": 3610,
  "db": "up",
  "embeddings": {
    "id": "local:Xenova/multilingual-e5-small:fp32:\"query: \"+\"passage: \"",
    "provider": "local", "model": "Xenova/multilingual-e5-small",
    "dimensions": 384, "dtype": "fp32", "ready": true
  },
  "sessions": { "total": 2, "streamable": 2, "sse": 0 },
  "allowedDocRoots": ["/docs"],
  "dataDir": "/data",
  "secretKeyConfigured": true,
  "uploads": { "maxFileBytes": 52428800, "maxFilesPerRequest": 500, "maxArchiveBytes": 268435456 }
}

Good liveness probe: ok === true && db === "up". Good readiness probe: also embeddings.ready. The response answers 503 with the same body while the database is unreachable, 200 otherwise — a monitor does not need a second check for that.

embeddings also carries the model’s input window and whether CHUNK_MAX_TOKENS fits inside it, so a misconfiguration that would silently truncate chunks shows up here before it shows up in search quality — see Configuration.

An anonymous caller gets a shorter answer — ok, version, db, authRequired and needsSetup — because the rest describes the machine. The fields a monitor watches are in both shapes.

Setup and sign-in

# sign in and keep the cookie in a jar, then use it like a browser would
curl -s -c jar -X POST $API/auth/login -H 'content-type: application/json' \
  -d '{"username":"alice","password":"…"}' | jq
curl -s -b jar $API/auth/me | jq

Single sign-on

Only present when this instance has an OIDC provider configured — see Single Sign-On for who can link and why root cannot.

Accounts

/api/users/* needs admin or root. Only a root account may create, change or delete another root account. PATCH /api/users/:id refuses 409 root_requires_unlink when asked to set role: "root" on an account that still has a linked SSO identity — unlink it first with DELETE /api/auth/oidc/link above.

409 guards the last active root account against deletion, demotion and being disabled; 403 guards an admin reaching for a root one, and anyone reaching for their own role or active flag.

# hand someone a new temporary password without touching the dashboard
ID=$(curl -s $API/users -H "Authorization: Bearer $TOKEN" | jq -r '.[] | select(.username=="alice") | .id')
curl -s -X POST $API/users/$ID/password -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{}' | jq -r .temporaryPassword

API tokens

/api/tokens* needs only a session — any account manages its own tokens, and there is no admin view over anyone else’s. This is how a script or a CI job gets a credential narrower than ADMIN_TOKEN: name it, optionally pin it to one project and an expiry date, and list exactly which routes it may call. The dashboard’s own Account menu → API tokens page is a client of exactly these endpoints — mint, list and revoke there without touching curl at all.

# mint a token that can only reindex one project — /api/tokens needs a session, not
# ADMIN_TOKEN, so sign in first (see "Setup and sign-in" above) and reuse the cookie jar.
# a cookie-authenticated request that changes something needs Sec-Fetch-Site too — see the
# CSRF rule above — curl never sends it on its own, unlike a real page's fetch would
curl -s -X POST $API/tokens -b jar \
  -H 'content-type: application/json' -H 'Sec-Fetch-Site: same-origin' \
  -d '{"name":"ci-reindex","scope":["POST /api/projects/:id/reindex"],"projectId":"'"$P"'"}' | jq

Deleting the project named in projectId deletes the token with it, rather than widening its reach.

Project members

Who reaches one project. root, admin and ADMIN_TOKEN reach every project without a membership, so only member accounts appear here.

Adding a member to a project a member account can then see:

curl -s -X PUT $API/projects/$P/members/$ID -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"role":"editor"}' | jq

400 if the target is an admin or root account — they already have access, so a membership row would say something untrue.

Projects

# create and index
curl -s -X POST $API/projects -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"handbook","rootPath":"/docs/handbook","index":true}' | jq

# re-index everything, every night
for id in $(curl -s $API/projects -H "Authorization: Bearer $TOKEN" | jq -r '.[].id'); do
  curl -s -X POST "$API/projects/$id/reindex" -H "Authorization: Bearer $TOKEN" > /dev/null
done

Watching a job

GET /api/projects includes a job for any project with a live run:

{ "phase": "embedding", "filesTotal": 84, "filesDone": 31, "filesSkipped": 22,
  "filesRemoved": 0, "chunksDone": 96,
  "sources": [{ "name": "handbook", "type": "local", "status": "synced" }],
  "queue": null }

phase is one of queued, syncing, scanning, embedding, finalizing, done, error. A queued job carries queue.aheadProjectName.

MCP access

GET /api/projects reports the current mode as mcpAuth. Closing an endpoint and minting a token:

curl -s -X PATCH $API/projects/$P/mcp-auth -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"mode":"token"}' | jq

curl -s -X POST $API/projects/$P/mcp-tokens -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"name":"claude-code"}' | jq -r .secret

The client then sends that secret as Authorization: Bearer ctxm_… on /mcp/<project-name> — see Connecting AI Clients.

Sources

Adding a git source:

curl -s -X POST $API/projects/$PROJECT_ID/sources \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
        "type": "git",
        "name": "api-docs",
        "label": "API reference",
        "config": { "url": "https://github.com/org/repo.git", "branch": "main", "subdir": "docs" },
        "secret": "ghp_…",
        "index": true
      }' | jq

config by type:

Uploads

SESSION=$(curl -s -X POST $API/projects/$P/sources/$S/uploads -H "Authorization: Bearer $TOKEN" | jq -r .session)
curl -s -X POST "$API/projects/$P/sources/$S/uploads/$SESSION/files" \
     -H "Authorization: Bearer $TOKEN" -F '[email protected];filename=guides/guide.md'
curl -s -X POST "$API/projects/$P/sources/$S/uploads/$SESSION/commit?mode=add" \
     -H "Authorization: Bearer $TOKEN"

Webhooks

See Push Webhooks.

Metrics

curl -s http://localhost:3444/metrics -H "Authorization: Bearer $METRICS_TOKEN"

GET /metrics is a separate, Prometheus-shaped endpoint (text/plain; version=0.0.4) with its own credential rules — it is not part of /api/* and is not public by default. It reports the indexing queue by lane, whether one is running, the last index run and whether it worked, searches by actor, the database connection pool, and whether the database itself answers.

It accepts a signed-in session, ADMIN_TOKEN, a METRICS_TOKEN bearer, or no credential at all when METRICS_PUBLIC=1 — see Configuration. It answers 200 even while the database is down, with contextator_db_up 0 and the rows that need a database left out, so a scrape gap is never how an outage gets reported. While the database is down only the three credentials that need no database read still work — ADMIN_TOKEN, METRICS_TOKEN, METRICS_PUBLIC — a session cookie is a database row and cannot be confirmed, so a browser presenting one gets 401 rather than 500 during an outage. That is the reason to configure METRICS_TOKEN before an outage, not during one.

Audit log

/api/audit needs root or admin — the log is instance-wide, and a project membership is not standing to read who was given the root role.

curl -s "$API/audit?action=DELETE%20/api/projects/:id&limit=50" \
  -H "Authorization: Bearer $TOKEN" | jq

How it is written

Every state-changing request above leaves a row in audit_events naming the account that made it — what was done, to which project, source, token, membership or account, and when. A sign-in and the creation of the first account are recorded too, and so is POST /oauth/authorize, a person granting a connector lasting read access to one project.

It is written by the policy layer, not by each handler, so there is no route that can be added without being covered — and none that can opt out. The exceptions are eight — a source’s test and upload-session routes, the three webhook deliveries (git, Notion, Confluence) and the three OAuth client-registration routes (register, token, revoke) — each named with its reason in src/auth/policy.ts.

A route that creates something names nothing in its own path, so the new object’s id is read back out of the response, through a table of fixed paths in that same file, and kept only when the value found there is a UUID — “who minted this token” is therefore a question the log answers, and it lines up against the revocation that names the same id.

What it does not hold

The rows carry no user content: a question, a document and an excerpt never reach a column of this table. The only body fields any action may record are named in that same policy file, each restricted to a closed set of values (mode is one of open/token/account, and so on). That keeps it a different record from the query log, which holds what agents asked, is governed by its own retention, and has its own per-project switch — the two are deliberately not one table.

Two things beyond that are deliberately not recorded. Refused requests — a refusal is the permission matrix working, and logging every probe would turn the table into a scan log; the one exception is a person refusing a connector at /oauth/authorize, which is somebody deciding rather than the matrix declining. And an action that changed something and then answered 5xx: the row is written only for a response under 400, so a handler that commits and then fails afterwards leaves none. No handler in this API is currently shaped that way, and SECURITY.md names it as the limit it is.

Reading it

GET /api/audit and the dashboard’s Audit log panel (account menu, beside Users) are both root/admin only. Each row renders as a sentence (“dana deleted a source from handbook”) rather than as the columns it is stored in. “Who” is two pickers: Actor is the label as it was recorded, and Account is the account id — which finds that account’s own actions together with those of every API token it owns, since a token’s label is only its name and owner and cannot gather them on its own. A project that has since been deleted still has its rows: project_id carries no foreign key, so the panel cannot look its name up, and says so on the row rather than leaving it blank.

The two columns the panel filters on — actor_label, because it outlives the account, and action — are indexed by migration 0011. At 200,004 rows a selective actor filter runs in 0.07 ms against 9.7 ms without the index, a page turn is 3 ms, and a first page is 19–52 ms because it also fills the filter dropdowns with three DISTINCT scans no index can help — paid once per filter change, never per page turn.

The log is not tamper-evident — anyone with database access can remove a row and nothing here would show it (SECURITY.md) — and rows older than AUDIT_LOG_RETENTION_DAYS are swept on the same quarter-hourly timer as expired sessions.

Errors

All errors are JSON: { "error": "conflict", "message": "…" }.

Notes

• Secrets are never returned by any endpoint; a source only reports hasSecret, and a password is never returned at all except the one time a temporary one is generated.
• POST /api/projects/:id/reindex is safe to call often: indexing is incremental.
• Authorization is decided server-side from one policy table covering routes by method and shape, so a new endpoint is protected the moment it exists. What the dashboard hides is cosmetic.
• The API is bound to the same port as the dashboard and the MCP endpoints, so anything that can reach one can reach the others (Security).