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.