API quickstart

Submit explicit event requirements and receive venues grouped as applicable on record, requiring verification, or not applicable because of a known conflict.

The authoritative machine-readable contract is /openapi.json.

Endpoints

• GET /health — Worker and D1 readiness.
• GET /v1/coverage — market, area and catalog coverage.
• POST /v1/match — stateless, requirements-first venue matching.
• POST /v1/compare — deprecated compatibility representation.
• POST /v1/transactions — local synthetic qualification experiment; requires an idempotency key.
• POST /v1/transactions/{id}/answers — record typed synthetic follow-up answers with optimistic revision.
• POST /v1/transactions/{id}/consent — authorize selected fictional suppliers and disclosed fields using reserved synthetic contact data.
• POST /v1/transactions/{id}/handover — create idempotent receipts from the in-process delivery simulator.

Try it

curl -sS http://127.0.0.1:8787/v1/coverage | jq

Run npm run smoke for a complete matching request. Matching uses only structured requirements and recorded evidence; reviews, ratings, popularity and sentiment do not affect order. Money values are integer USD cents. Public price references are context only; calculated estimates require an active supplier-approved rule.

Local synthetic mode uses five fictional records. Public mode includes only reviewed, fresh, unsuppressed profiles and never mixes in those fixtures. A listing does not imply supplier participation.

Operators can review source drafts and inspect server-recorded review metrics at /admin/; all private data and mutations require the configured operator token. Run npm run smoke:public -- https://your-staging-host to check public mode.

The M1 transaction routes are disabled outside local synthetic mode and require a configured synthetic-agent bearer token. They reject real contact data, accept only explicitly fictional names and .invalid email addresses, and never communicate outside the in-process simulator.