HTTP API reference

​

Motivation

​

Conventions

• Auth. Most routes require auth:sanctum (SPA cookie or a personal access token). Admin routes additionally carry a role: or can: gate. The embeddable widget authenticates with a widget.key (public key + minted session token). A guest hitting an authed route gets 401; an authenticated caller without the required role gets 403.
• Tenancy. Every request resolves a tenant; queries are scoped to it. See security & threat model.
• Failures are loud. Endpoints map failure to the correct status (404 missing, 422 validation, 429 throttle, 5xx downstream) — never 200 with an empty body.

​

Authentication — /api/auth

​

KB chat & search — /api/kb

​

Ingestion — /api/kb/ingest

{
  "documents": [
    {
      "project_key": "handbook",          // optional, max 120; default KB_INGEST_DEFAULT_PROJECT
      "source_path": "onboarding.md",      // required, max 500
      "title": "Onboarding",               // optional, max 255
      "mime_type": "text/markdown",        // optional, default text/markdown
      "content": "# Onboarding\n…",         // required, max 7_000_000 (base64 for binary)
      "metadata": { }                       // optional
    }
  ]
}

​

Promotion pipeline — /api/kb/promotion

• suggest — { transcript (≤50000), project_key?, existing_slugs? }.
• candidates — { markdown (≤200000) } → 200 { valid: true, parsed: {…} } on success, or 422 { valid: false, errors: {…} } on validation failure.
• promote — validates the draft (422 on bad/absent frontmatter, 503 when promotion is disabled), then returns 202 with a paused-flow envelope containing a nested approval object (single-use token, approve_url, approve_path, …). The actual disk write happens only on approve.

​

Conversations, presets & notifications

​

Admin — /api/admin

​

Embeddable widget — /api/widget

​

MCP — /mcp/kb

​

Worked example

# 1. authenticate (token), then ask a grounded question
curl -s https://your-host/api/kb/chat \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"question":"what cache did we standardise on?","filters":{"project_keys":["platform"]}}'
# → { "answer": "...", "citations": [...], "confidence": 0.82, "refusal_reason": null, "meta": {...} }

# 2. validate a promotion draft (writes nothing)
curl -s https://your-host/api/kb/promotion/candidates \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"markdown":"---\ndoc_id: dec-cache-v2\nslug: dec-cache-v2\n---\n# ..."}'
# → 200 { "valid": true, "parsed": {...} }   (or 422 { "valid": false, "errors": {...} })