Kwizmo Local^™ API — Developer Manual

Creates a new user account.

Request (JSON)

{
  "email": "alice@example.com",
  "username": "alice",
  "password": "secret123"
}

Response (success)

{
  "status": "ok",
  "message": "User registered successfully",
  "loc": "..."
}

Response (username or email already taken)

HTTP 400
{ "detail": "User could not be registered" }

Notes

• The very first account ever registered becomes headadmin, active immediately.
• All later accounts are created as admin, status: 0 (inactive) until a headadmin activates them.
• Recorded in the audit log as register (status ok or denied, with a reason such as "username taken" or "email taken").

Authenticates a user and issues a new session api_key. Each login creates its own independent session — it does not invalidate any other session, including a previous session for the same user (e.g. logged in on another device) or any other user's active session. See Authentication & session model.

Request (JSON)

{
  "username": "alice",
  "password": "secret123"
}

Response (headadmin)

{
  "status": "ok",
  "api_key": "0123abcd...",
  "users": [ /* full users.json content */ ],
  "role": "headadmin"
}

Response (regular user)

{
  "status": "ok",
  "api_key": "abcd0123...",
  "users": [ /* only this user's own record */ ],
  "role": "admin"
}

Response (inactive user)

""  (empty string body)

Response (wrong credentials)

{ "status": "error", "message": "Invalid credentials" }

Notes

• headadmin receives every user's record in users; other roles receive an array containing only their own record (used by the dashboard's Users tab to show a self-service password-change view — see /saveUser).
• Recorded in the audit log as login (ok / denied, with reason "inactive user" or "invalid credentials").

Verifies that a previously-issued api_key is still valid and returns the associated username/role — without requiring the password again. Used by the dashboard to restore the logged-in view after a browser refresh (F5 / Ctrl+F5) instead of dropping back to the login screen.

Request

GET /whoami
kwizmo_login_header: <api_key>

Response (valid session, regular user)

{
  "status": "ok",
  "username": "alice",
  "role": "admin",
  "users": [ /* only this user's own record */ ]
}

Response (session no longer valid)

{ "status": "error", "message": "Session no longer valid" }

Invalidates only the calling session's api_key server-side, so a stored key (e.g. kept in a browser's sessionStorage) can no longer be used afterward. Other sessions — including other active logins for the same user, or any other user's session — are unaffected.

Request

POST /logout
kwizmo_login_header: <api_key>

Response

{ "status": "ok" }

Notes

• Recorded in the audit log as logout.

Serves the dashboard's dashboard.html as-is. This is the same web UI a browser sees when visiting the server's root URL; it authenticates separately via /login from within the page.

Serves this developer manual (kwizmo_api_developer_manual_html.html) directly from disk. Linked from the dashboard's "📘 API Developer Manual" button.

Returns domains (Qdrant collections) visible to the current user. headadmin sees every collection on the server; other roles see only the domains listed in their own domains field.

Request

GET /domains
kwizmo_login_header: <api_key>

Response

{ "domains": ["alice_docs", "bob_files"] }

Checks whether a domain already exists, applying the same <username>_<domain> prefixing used by /ingest and /crawl. Since those two endpoints silently auto-create a domain on first use, this lets a client (such as the dashboard) confirm with the user before that happens, rather than a new domain appearing unannounced.

Request

GET /domain_exists?domain=ajpes
kwizmo_login_header: <api_key>

Response

{
  "status": "ok",
  "domain": "alice_ajpes",
  "exists": false
}

Returns raw Qdrant collection metadata for a domain: vector count, indexing status, distance metric, HNSW/optimizer configuration, and so on. Powers the dashboard's "Vector DB Config" tab.

Request

GET /collection_stats?domain=alice_docs
kwizmo_login_header: <api_key>

Response

{
  "status": "green",
  "vectors_count": 1204,
  "points_count": 1204,
  "config": { "params": { "vectors": { "size": 768, "distance": "Cosine" } }, ... },
  ...
}

Permanently deletes an entire domain (the whole Qdrant collection, including all indexed files/pages within it). Irreversible.

Request (form)

domain=alice_docs

Response

{ "status": "ok", "domain": "alice_docs" }

Notes

• The caller must own the domain (its name must start with <their_username>_); otherwise the request is silently denied (empty response).
• Recorded in the audit log as delete_collection.

Uploads a file to be chunked, embedded, and stored in a domain. Chunking strategy, chunk size, and overlap are chosen automatically based on file type — structured formats (code, markdown) are split on natural boundaries (functions, headers) rather than raw word count wherever possible. See Chunking strategy by file type below for full details.

Supported file types

.pdf, .docx, .doc (best-effort — see Chunking strategy by file type), .txt, .md/.markdown, .csv/.tsv, and source code (.py .js .jsx .ts .tsx .java .c .h .cpp .hpp .cs .go .rb .php .rs .swift .kt .sql .sh). Anything else returns "Unsupported file type".

Request (multipart/form-data)

file: (binary file)
domain: docs

Example curl

curl -X POST "https://localhost:5000/ingest" \
  -H "kwizmo_login_header: <api_key>" \
  -F "domain=docs" \
  -F "file=@manual.pdf"

Response (success)

{
  "status": "ok",
  "domain": "alice_docs",
  "file": "manual.pdf",
  "chunks_indexed": 42
}

Response (errors)

{"status":"error","message":"Empty file"}
{"status":"error","message":"File produced no chunks"}
{"status":"error","message":"Unsupported file type"}
{"status":"error","message":"Could not extract readable text from this .doc file. ..."}
{"status":"error","message":"Failed to save to the vector database: ..."}

Chunk metadata by file type

Type	Chunk metadata recorded
PDF	source, page (1-indexed), chunk_index
DOCX	source, paragraph (1-indexed), chunk_index
DOC (legacy)	source, paragraph (1-indexed, based on extracted text runs — not identical to the original paragraph structure), chunk_index
TXT	source, paragraph (1-indexed, split on newlines), chunk_index
Markdown	source, heading (nearest enclosing header text), chunk_index
Source code	source, language, function_name (function/class/method name when identifiable), chunk_index
CSV/TSV	source, chunk_index (header row repeated in every chunk)

Notes

• Recorded in the audit log as ingest_file, including chunks_indexed on success.

Lists the distinct files/URLs currently indexed in a domain, sorted case-insensitively.

Request

GET /files?domain=alice_docs
kwizmo_login_header: <api_key>

Response

{ "files": ["manual.pdf", "https://example.com/pricing", "notes.txt"] }

Notes

• Entries can be plain filenames (from /ingest) or full URLs (from /crawl) — both are stored in the same file payload field.
• The domain is auto-created if it doesn't exist yet (so this returns an empty list rather than an error for a brand-new name).

Deletes every indexed chunk belonging to one file or URL from a domain.

Request (form)

domain=alice_docs
filename=manual.pdf

Response

{
  "status": "ok",
  "domain": "alice_docs",
  "file": "manual.pdf",
  "deleted_points": 12
}

Notes

• Recorded in the audit log as delete_file.

Deletes every indexed chunk belonging to any number of files/URLs in one call — the collection is scanned once regardless of batch size, which matters for domains with thousands of documents. Powers the dashboard's "delete filtered files" action.

Request (form)

domain=alice_docs
filenames=["manual.pdf","draft-v1.pdf","draft-v2.pdf"]

"filenames" is a JSON-encoded array of filenames/URLs, exactly as they appear in GET /files.

Response

{
  "status": "ok",
  "domain": "alice_docs",
  "deleted_files": ["draft-v1.pdf", "draft-v2.pdf", "manual.pdf"],
  "deleted_points": 47,
  "not_found": []
}

Notes

• not_found lists any requested filenames that didn't match a point in the domain (e.g. already deleted).
• Recorded in the audit log as delete_files_bulk, including the list of files actually deleted.

Diagnoses network reachability to a URL, staged the same way curl -v would report it: DNS resolution, a raw TCP connect, then the full HTTP request (including the TLS handshake for https:// URLs) — each timed independently, plus an informational robots.txt check. Answers "why can't the crawler reach this site?" (DNS failure vs. network/firewall block vs. a slow-but-reachable server vs. the site simply returning an HTTP error) without needing to shell into the container to run curl/ping/nslookup by hand.

Request (JSON)

{ "url": "https://example.com" }

Response — reachable

{
  "status": "ok",
  "result": {
    "url": "https://example.com",
    "hostname": "example.com",
    "port": 443,
    "dns": { "status": "ok", "duration_ms": 12.4, "resolved_ip": "93.184.216.34", "error": null },
    "tcp_connect": { "status": "ok", "duration_ms": 45.1, "error": null },
    "http_request": { "status": "ok", "duration_ms": 210.7, "status_code": 200, "content_type": "text/html; charset=UTF-8", "content_length": 1256, "error": null },
    "robots_txt": { "status": "checked", "allowed": true, "error": null },
    "overall": "reachable",
    "summary": "Reachable. DNS: 12.4ms, TCP connect: 45.1ms, full HTTP request: 210.7ms. HTTP 200."
  }
}

Response — connection timeout (the most common real-world failure)

{
  "status": "ok",
  "result": {
    "url": "https://www.example-slow-site.com",
    "hostname": "www.example-slow-site.com",
    "port": 443,
    "dns": { "status": "ok", "duration_ms": 18.2, "resolved_ip": "203.0.113.5", "error": null },
    "tcp_connect": { "status": "timeout", "duration_ms": 15003.4, "error": "Connection to www.example-slow-site.com:443 timed out after 15s" },
    "http_request": { "status": "not_attempted", "duration_ms": null, "status_code": null, "content_type": null, "content_length": null, "error": null },
    "robots_txt": { "status": "not_attempted", "allowed": null, "error": null },
    "overall": "connect_timeout",
    "summary": "DNS resolved 'www.example-slow-site.com' to 203.0.113.5 in 18.2ms, but connecting to www.example-slow-site.com:443 timed out after 15s. This points to a network path problem (firewall, routing, or the remote host/service not accepting connections) rather than a DNS or application-level issue."
  }
}

overall values

Value	Meaning
reachable	DNS, TCP connect, and the HTTP request all succeeded with a 2xx/3xx response.
http_error	Connected fine, but the server returned a non-2xx/3xx HTTP status — not a network problem.
dns_failure	The hostname could not be resolved at all — likely a typo, or this server has no working DNS.
connect_timeout	DNS resolved fine, but the TCP connection to the resolved IP timed out — a network path/firewall/routing problem, or the remote service isn't accepting connections on that port.
connect_failed	DNS resolved fine, but the TCP connection failed immediately (e.g. connection refused) rather than timing out.
tls_error	TCP connected, but the TLS/SSL handshake failed (e.g. certificate problem).
http_timeout	TCP connected, but the full HTTP request (including TLS) didn't complete in time — the server is slow/unresponsive at the HTTP layer specifically.
http_failed	TCP connected, but the HTTP request failed for some other reason.
invalid_url	url doesn't start with http:///https://, or no hostname could be parsed from it.

Notes

• This is a synchronous call, not a background job like /crawl — a single URL check is fast enough not to need progress polling. Worst case it takes roughly up to CRAWL_TIMEOUT_SECONDS (default 15s) per stage attempted.
• The robots_txt check is informational only, run after the reachability stages regardless of their outcome (unless the URL is invalid) — it doesn't affect overall.
• Uses the same CRAWL_TIMEOUT_SECONDS environment variable as page/document fetching for consistency with actual crawl behavior.
• Recorded in the audit log as test_connectivity, including the resulting overall status.

Crawls outward from a starting URL (breadth-first, same site only) and finds every page URL reachable from it, without indexing anything. Used to let the user pick which pages to include before committing to a full crawl.

Request (JSON)

Field	Type	Default	Notes
url	string	—	Required. The page to start discovery from.
max_pages	int	5000	Stop discovery once this many pages/documents have been found. Hard-capped server-side at MAX_ALLOWED_CRAWL_PAGES (default 5000) regardless of what's requested.
max_depth	int	2	How many link-hops away from url to follow. Hard-capped server-side at MAX_ALLOWED_CRAWL_DEPTH (default 10).

{ "url": "https://example.com/docs", "max_pages": 200, "max_depth": 3 }

Response — discovery started

{
  "status": "ok",
  "discover_id": "3b8e91a0-...",
  "start_url": "https://example.com/docs",
  "max_pages": 200,
  "max_depth": 3
}

The returned max_pages/max_depth reflect the values actually applied (after server-side clamping), which may be lower than what was requested. Use discover_id with /discover_progress to follow along and get the final page list — this response does not include the page list itself. The final list from /discover_progress mixes HTML page URLs and document URLs together; a client can distinguish them by checking the URL's file extension against the list in Chunking strategy by file type, the same way the dashboard does.

Response (immediate validation errors)

{"status":"error","message":"URL must start with http:// or https://"}
{"status":"error","message":"This URL is disallowed by the site's robots.txt"}
{"status":"error","message":"max_pages must be at least 1"}
{"status":"error","message":"max_depth must be 0 or greater"}

Notes

• Default limits are 5000 pages and a link depth of 2 from the start URL — both are request parameters, configurable from the dashboard's crawl UI as well as directly via the API, not fixed. The maximum either can be set to (MAX_ALLOWED_CRAWL_PAGES / MAX_ALLOWED_CRAWL_DEPTH) is itself configurable via environment variables (both default to matching the request defaults), to prevent an accidental request from launching an extremely long-running crawl against a huge site.
• robots.txt is respected — disallowed pages and documents are never queued or returned. If a site's robots.txt itself can't be retrieved cleanly (missing, errors out, times out, or returns anything other than 200 OK), that fails open — crawling proceeds as if no robots.txt exists — rather than being treated as "disallow everything," which previously caused otherwise-normal sites to fail discovery/crawling with no clear error. Fetching robots.txt uses its own short, non-retried timeout (default 5s, configurable via ROBOTS_TXT_TIMEOUT_SECONDS) rather than the same timeout/retry settings as page content — this keeps otherwise-fast endpoints like this one and /test_connectivity from being blocked for a long time by a single slow or unreachable robots.txt. The result is cached per site after the first check.
• A short delay is applied between page fetches during discovery, to avoid hammering the target site.
• Each page fetch (here and in /crawl) automatically retries once after a connection-level failure (timeout, DNS error, connection refused/reset) before giving up — HTTP error responses like 404/500 are never retried, since those are a definitive answer from the server rather than a network glitch. Both the connect/read timeout (default 15s) and retry count (default 1) are configurable via the CRAWL_TIMEOUT_SECONDS and CRAWL_FETCH_RETRIES environment variables if your network has consistently higher latency.

Polled while a POST /crawl_discover call is running in the background. Returns the page currently being checked and how many pages have been found so far. Once done is true, either the final pages list is populated, or status is "error" if the site couldn't be reached at all.

Request

GET /discover_progress?discover_id=3b8e91a0-...
kwizmo_login_header: <api_key>

Response — in progress

{
  "status": "ok",
  "done": false,
  "start_url": "https://example.com/docs",
  "current_url": "https://example.com/docs/getting-started",
  "found": 4,
  "pages": [],
  "max_pages": 50,
  "hit_page_limit": false
}

Response — finished, under the page limit

{
  "status": "ok",
  "done": true,
  "start_url": "https://example.com/docs",
  "current_url": null,
  "found": 12,
  "pages": [
    "https://example.com/docs",
    "https://example.com/docs/getting-started",
    "https://example.com/docs/faq"
  ],
  "max_pages": 50,
  "hit_page_limit": false
}

Response — finished, page limit reached (site may have more pages)

{
  "status": "ok",
  "done": true,
  "start_url": "https://example.com/docs",
  "current_url": null,
  "found": 5000,
  "pages": [ /* 5000 URLs */ ],
  "max_pages": 5000,
  "hit_page_limit": true
}

When hit_page_limit is true, discovery stopped because it hit max_pages, not because the whole site was exhausted — there may be more pages on the site that were never reached. Re-run /crawl_discover with a higher max_pages to find more.

Response — finished with an error (site unreachable)

{
  "status": "error",
  "message": "Could not reach or crawl the given URL: Connection to example.com timed out. (connect timeout=15)",
  "done": true
}

Response — unknown or expired discover_id

{ "status": "error", "message": "Unknown or expired discover_id" }

Notes

• Progress is held in memory only (not persisted to disk), the same as /crawl_progress — it's meant for live polling during discovery, not as a permanent record. A finished discovery's progress entry is kept for about 30 minutes then discarded.
• Recommended polling interval: about once per second — frequent enough to feel live, without hammering the server.

Crawls either a single URL or a specific list of pages, indexes their content into a domain, and persists a crawl job. If a page/document was already indexed before (matched by URL), its old content is removed and replaced — the same "recrawl" semantics used for scheduled re-runs.

Request (JSON)

Field	Type	Default	Notes
domain	string	—	Required. Short or full domain name.
url	string	—	Required. The page to crawl, or the seed URL if crawl_all_pages is true.
crawl_all_pages	bool	false	If true, crawls every URL in pages instead of just url.
pages	array of strings	null	Required when crawl_all_pages is true — typically the list returned by /crawl_discover, filtered to what the user selected.
recrawl_interval	string	"none"	One of "none", "daily", "weekly", "biweekly". Schedules automatic future recrawls of this job.
recrawl_hour	int	random hour 0–5	Hour of day (0–23, server local time) to run the recrawl. If omitted, a random hour between midnight and 6am is chosen and used consistently for that job going forward — not re-randomized on every restart. Any hour can be chosen; the 0–5 default is only a suggestion for off-peak timing.
recrawl_days	array of strings	all 7 days	Which days of the week to recrawl on, from ["mon","tue","wed","thu","fri","sat","sun"]. Defaults to every day (weekends included) if omitted or empty. Invalid/unrecognized values are ignored; if none remain valid, falls back to all 7 days.
max_pages	int	50	Only relevant when crawl_all_pages is true and re-discovery runs on a future recrawl (see below) — stored on the job and reused so scheduled recrawls use the same site-scan scope originally chosen. Hard-capped server-side at MAX_ALLOWED_CRAWL_PAGES.
max_depth	int	2	Same as max_pages — stored on the job for future recrawl re-discovery. Hard-capped server-side at MAX_ALLOWED_CRAWL_DEPTH.

Example — single page, no schedule

{
  "domain": "docs",
  "url": "https://example.com/pricing",
  "crawl_all_pages": false,
  "recrawl_interval": "none"
}

Example — whole site, recrawl weekly at the suggested off-peak default

{
  "domain": "docs",
  "url": "https://example.com/docs",
  "crawl_all_pages": true,
  "pages": [
    "https://example.com/docs",
    "https://example.com/docs/getting-started"
  ],
  "recrawl_interval": "weekly"
}

Omitting recrawl_hour/recrawl_days here means: a random hour between midnight and 6am, every day of the week.

Example — daily recrawl, weekdays only, at 2pm

{
  "domain": "docs",
  "url": "https://example.com/docs/pricing",
  "crawl_all_pages": false,
  "recrawl_interval": "daily",
  "recrawl_hour": 14,
  "recrawl_days": ["mon", "tue", "wed", "thu", "fri"]
}

Response — crawl started

{
  "status": "ok",
  "crawl_id": "9f3a7c21-...",
  "domain": "alice_docs",
  "pages_to_crawl": 2
}

Use crawl_id with /crawl_progress to follow along and get the final results — this response does not include page-by-page results itself.

Notes

• Every call creates a new crawl job, even with recrawl_interval: "none" — there is no "one-off, don't remember this" mode. Remove unwanted jobs via /delete_crawl_job.
• A short delay is applied between each page fetch, and robots.txt is respected the same way as in /crawl_discover.
• Recorded in the audit log as a job-level crawl summary entry (including a removed count), plus one crawl_page entry per page (success, removal, or failure).
• See /run_crawl_job_now and recrawl behavior below for how crawl_all_pages jobs also detect pages removed from a site's navigation entirely, not just pages whose exact URL now 404s.

Polled while a POST /crawl call is running in the background. Returns which page is currently being fetched, how many pages have been processed so far, and the results collected up to that point. Once done is true, the response reflects the final outcome — the same information the old synchronous /crawl response used to return directly.

Request

GET /crawl_progress?crawl_id=9f3a7c21-...
kwizmo_login_header: <api_key>

Response — in progress

{
  "status": "ok",
  "done": false,
  "total": 12,
  "current_index": 4,
  "current_url": "https://example.com/docs/getting-started",
  "domain": "alice_docs",
  "results": [
    { "url": "https://example.com/docs", "title": "Docs", "chunks_indexed": 6 },
    { "url": "https://example.com/docs/faq", "title": "FAQ", "chunks_indexed": 3 },
    { "url": "https://example.com/docs/old-page", "removed": true, "reason": "HTTP 404", "deleted_points": 5 },
    { "url": "https://example.com/whitepaper.pdf", "title": "whitepaper.pdf", "chunks_indexed": 9, "is_document": true }
  ],
  "job_id": null,
  "pages_crawled": null
}

Response — finished

{
  "status": "ok",
  "done": true,
  "total": 12,
  "current_index": 12,
  "current_url": null,
  "domain": "alice_docs",
  "results": [ /* full list of per-page results */ ],
  "job_id": "5a1c2e3f-...",
  "pages_crawled": 12
}

Response — unknown or expired crawl_id

{ "status": "error", "message": "Unknown or expired crawl_id" }

Notes

• Progress is held in memory only (not persisted to disk) — it is meant for live polling during a crawl, not as a permanent record. A finished crawl's progress entry is kept for about 30 minutes then discarded; the crawl's actual results remain available afterward via /crawl_jobs (as the job's last_result) and via /audit_logs.
• A server restart while a crawl is in progress loses that crawl's live progress tracking (you'll get "Unknown or expired crawl_id" on the next poll), though the crawl job itself, once it completes, is still persisted normally.
• Recommended polling interval: about once per second — frequent enough to feel live, without hammering the server.

Lists crawl jobs visible to the current user (jobs they created, or jobs belonging to a domain they have access to), optionally filtered to one domain.

Request

GET /crawl_jobs?domain=alice_docs
kwizmo_login_header: <api_key>

domain is optional — omit it to list jobs across all domains visible to the caller.

Response

{
  "jobs": [
    {
      "id": "5a1c2e3f-...",
      "domain": "alice_docs",
      "start_url": "https://example.com/docs",
      "crawl_all_pages": true,
      "pages": ["https://example.com/docs", "..."],
      "recrawl_interval": "weekly",
      "recrawl_hour": 3,
      "recrawl_days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
      "max_pages": 50,
      "max_depth": 2,
      "created_by": "alice",
      "created_at": "2026-07-01T12:00:00Z",
      "last_run": "2026-07-08T12:00:00Z",
      "last_result": [ /* per-page results from the most recent run */ ]
    }
  ]
}

recrawl_hour reflects the hour actually resolved at job creation (either what was requested, or the randomly suggested off-peak default) — it does not change on subsequent server restarts. max_pages/max_depth are the site-scan limits this job was created with, and are reused whenever a scheduled recrawl re-discovers the site's current pages.

Triggers an immediate run of an existing crawl job, regardless of its configured recrawl interval. Uses the same recrawl semantics as a scheduled run (existing page content is removed and replaced with a freshly crawled version) — this is also how removed pages get cleaned up (see below).

Request (form)

job_id=5a1c2e3f-...

Response

{
  "status": "ok",
  "job_id": "5a1c2e3f-...",
  "message": "Recrawl started in the background"
}

Notes

• Runs asynchronously in the background — this endpoint returns immediately rather than waiting for every page to finish, so it stays fast even for large jobs.
• Progress and outcome are recorded in the audit log the same way as an automatic scheduled recrawl (crawl_page per page — including removals, plus a summary recrawl entry with a removed count), alongside a run_crawl_job_now entry marking that it was manually triggered.
• Poll GET /crawl_jobs after a short delay to see the updated last_run timestamp, results, and (for crawl_all_pages jobs) the refreshed pages list.

Stops and removes a crawl job, cancelling any future scheduled recrawls. Pages already indexed by that job remain in the domain — this only removes the job's scheduling record, not previously-crawled content.

Request (form)

job_id=5a1c2e3f-...

Response

{ "status": "ok", "job_id": "5a1c2e3f-..." }

Response (job not found)

{ "status": "error", "message": "Job not found" }

Notes

• Recorded in the audit log as delete_crawl_job.

Searches a single domain using the sentence-transformer embeddings and returns the top-k most similar chunks from Qdrant, with their similarity scores and source metadata.

Request (form)

query=How do I configure X?
domain=alice_docs
top_k=5

Response

{
  "domain": "alice_docs",
  "query": "How do I configure X?",
  "results": [
    {
      "score": 0.8421,
      "text": "...",
      "source": "manual.pdf",
      "page": 2,
      "paragraph": null,
      "chunk_index": 3,
      "id": "b7e2..."
    }
  ]
}

Notes

• Returns "" (empty string) if the user is inactive or doesn't have access to the requested domain.
• Recorded in the audit log as search, including the query text and result count.

Searches every domain assigned to the current user in one call and returns a single combined, re-ranked result set.

Request (form)

query=How do I configure X?
top_k=5

Response

{
  "domain": "alice_docs,alice_notes",
  "query": "How do I configure X?",
  "results": [ /* top_k results, combined and re-sorted by score across all domains */ ]
}

Notes

• The user must have at least one domain listed in their own domains field — this reads that field directly, so a headadmin account (whose own domains is typically empty, since it has implicit access to everything) will get "No domains assigned for this user" here even though it can access every domain via other endpoints.
• domain in the response is the raw comma-separated string from the user's profile, not a list.

Takes a query plus a set of retrieved chunks (typically the results from /search or /searchDomains) and asks an AI provider — OpenAI or Anthropic (Claude) — to write an answer grounded only in that context.

Request (JSON) — OpenAI

{
  "domain": "alice_docs",
  "query": "How to configure X?",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "openAIKey": "sk-...",
  "creativity": 0.2,
  "results": [
    {"score": 0.9, "text": "...", "source": "manual.pdf", "page": 2}
  ]
}

Request (JSON) — Anthropic

{
  "domain": "alice_docs",
  "query": "How to configure X?",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "anthropicKey": "sk-ant-...",
  "creativity": 0.2,
  "results": [
    {"score": 0.9, "text": "...", "source": "manual.pdf", "page": 2}
  ]
}

Response

{
  "domain": "alice_docs",
  "query": "How to configure X?",
  "answer": "...AI-generated answer..."
}

Fields

Field	Type	Required	Notes
provider	string	No (default "openai")	Either "openai" or "anthropic".
model	string	Yes	OpenAI example: gpt-4o-mini. Anthropic example: claude-sonnet-4-5.
openAIKey	string	Required if provider is "openai"	Your OpenAI API key. Ignored for Anthropic requests.
anthropicKey	string	Required if provider is "anthropic"	Your Anthropic API key. Ignored for OpenAI requests.
creativity	float	Yes	Passed through as temperature. For Anthropic this is clamped server-side to Anthropic's valid 0–1 range even if a higher value (up to OpenAI's 0–2 scale) is sent.
results	array	Yes	The context chunks to answer from — each needs at least score and text. Optional fields page, paragraph, function_name, heading, language are accepted but not required. Sorted by score descending server-side before being joined into the prompt.

Notes

• If provider is omitted, defaults to "openai" for backward compatibility.
• Missing the required key for the chosen provider, or an unrecognized provider value, returns a short message in answer and does not call any AI provider.
• The system prompt instructs the model to answer using only the provided context, for both providers.
• Anthropic responses are generated with max_tokens: 4096 server-side.
• Recorded in the audit log as query_answer (provider, model, domain, query) — API keys are never written to the audit log.

Bulk-saves the full user list: activation status, role, assigned domains, and password resets.

Request (JSON array)

[
  {
    "email": "bob@example.com",
    "username": "bob",
    "password": "$2b$12$...",
    "role": "admin",
    "status": 1,
    "domains": "alice_docs"
  }
]

Each entry needs email, username, password, role, status (0 or 1), and domains (comma-separated string).

Response

{ "status": "ok", "message": "Users saved successfully!" }

Response (not headadmin, or inactive)

{ "status": "failed", "message": "Users not saved successfully!" }

Notes

• If a submitted password value isn't already a bcrypt hash, it's treated as a new plain-text password and hashed before saving — so the dashboard can leave existing hashes untouched while only sending a new value for users whose password is being reset.
• Recorded in the audit log as save_users, including a per-user diff of what changed (password reset, status, role, domains).

Returns structured audit log entries recording who did what across the whole system — logins, registrations, uploads/deletions, website crawls (including each individual page crawled or recrawled), searches, AI-provider queries, and user-management changes.

Query parameters

Param	Type	Required	Notes
limit	int	No (default 200, max 2000)	Maximum entries returned, most recent first.
username	string	No	Exact match filter on the acting user.
action	string	No	Exact match filter on the action name — see Audit action types.

Example request

GET /audit_logs?limit=100&username=alice&action=crawl_page
kwizmo_login_header: <api_key>

Response

{
  "status": "ok",
  "count": 2,
  "logs": [
    {
      "timestamp": "2026-07-09T14:02:11.203Z",
      "user": "alice",
      "action": "crawl_page",
      "status": "ok",
      "details": {
        "domain": "alice_docs",
        "url": "https://example.com/pricing",
        "chunks_indexed": 4,
        "job_id": "5a1c..."
      }
    },
    {
      "timestamp": "2026-07-09T14:01:58.771Z",
      "user": "alice",
      "action": "login",
      "status": "ok",
      "details": { "role": "admin" }
    }
  ]
}

Response (non-headadmin)

{ "status": "error", "message": "Only headadmin can view audit logs", "logs": [] }

Notes

• Entries are stored as JSON Lines in /data/audit.log inside the container, independent of the free-text application log (/data/app.log).
• API keys (OpenAI, Anthropic, and the session kwizmo_login_header key) are never written to audit entries.