Technical guide

Web API Quickstart

This guide is for external developers. You do not need internal Docker networks. Use HTTPS endpoints only.

This docs site uses “WebCrux” to mean the public-facing API layer that proxies to the Engine and exposes user/workspace surfaces (history, saved items, proof sharing). Depending on deployment, you may see:

Engine-style endpoints (often under /v1/*) for answers/search/receipts.
WebCrux BFF endpoints (often under /api/*) for history/saved/workspaces and UI-specific flows.

Base concepts

Auth bearer tokens issued per workspace.
Modes: light, verified, audit.
Evidence is formed via QUORUM (MiSES) (Minimal Evidence Sets) and sealed into CROWN receipts (signed, replayable).
Results include receipt IDs; you can fetch history and saved items.

Create an answer

Example with curl. Replace placeholders with your values.

curl -sS -X POST "$WEBCRUX_API/v1/answers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Why is the sky blue?",
    "mode": "verified",
    "k": 10
  }'

Notes:

Some deployments may accept query instead of q; prefer q when available to match the Engine/SDK examples in this docs set.
Responses typically include an answer, artefacts, findings, and a receipt_id (or equivalent identifier).

History API

List recent runs for your workspace.

curl -sS "$WEBCRUX_API/api/history?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Saved API

Save an answer for later reference, then retrieve it.

# Save
curl -sS -X POST "$WEBCRUX_API/api/saved" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "receipt_id": "<id>", "title": "Sky colour" }'

# Retrieve
curl -sS "$WEBCRUX_API/api/saved/<id>" \
  -H "Authorization: Bearer $TOKEN"

Rate limits and retries

Respect 429 with Retry-After header.
Use idempotent keys for repeat submissions where supported.
Exponential backoff for transient 5xx.

Errors

Errors return JSON with code, message, details and a request id. Log the id when contacting support.

Web API Quickstart