Hosted REST API
The Veto merchant control plane — the hosted REST API behind merchants.veto-ai.com. Provision merchants, manage catalog, policy, and receiving, serve discovery manifests, ingest gate outcomes, and read reputation.
The hosted control plane is the REST API a merchant uses when they don't want to run the self-hosted SDK. It provisions merchants, mints the receipt-signing key, manages catalog + policy + receiving, serves the public discovery surface, ingests gate outcomes from a self-hosted SDK, and serves bidirectional reputation.
- Base URL —
https://api.veto-ai.com - Discovery host —
https://<slug>.veto-checkout.com(public manifest + JWKS) - All bodies are JSON. Status codes are used semantically.
- Every error has the shape
{ "reason_codes": [...], "error_human": "..." }— see Errors.
Two planes, one protocol.
The Agentic Checkout Protocol is what an agent talks to (/agent/checkout, /agent/catalog).
This Hosted REST API is what a merchant talks to (/v1/merchants, /v1/policy, …). Both speak the
same reason_codes vocabulary and the same money rules (exact decimal strings, never floats).
Endpoint groups
| Group | Base path | Auth | What it does |
|---|---|---|---|
| Auth & sign-in | /v1/auth, /v1/me | public → mints key | Magic-link + CLI device-code sign-in. |
| Merchants | /v1/merchants | API key | Create a merchant; mint receipt key; serve per-merchant JWKS. |
| Catalog | /v1/catalog | API key | CRUD products (exact-decimal pricing). |
| Receiving | /v1/receiving | API key | The pay_to destination(s), validated at write time. |
| Policy | /v1/policy | API key | Immutable, versioned acceptance policy. |
| Validate & publish | /v1/validate, /v1/publish | API key | The publish gate. |
| Orders | /v1/orders | API key | Read-only activity feed. |
| Manifest & JWKS | /.well-known/*, /m/* | public | The agent-facing discovery surface. |
| Ingest | /v1/ingest | API key | The reporting path from a self-hosted SDK. |
| Reputation | /v1/reputation, /api/v1/reputation | public / lenient | Bidirectional agent + merchant scores. |
| Webhooks | event deliveries | HMAC | Signed event deliveries + retry contract. |
Health & readiness
Two unauthenticated operational endpoints sit at the root.
| Method & path | Response |
|---|---|
GET /healthz | 200 { "ok": true } — liveness; never touches the DB. |
GET /readyz | 200 { "ok": true, "db": true } when dependencies are reachable; 503 with DATABASE_UNAVAILABLE otherwise. |
curl -s https://api.veto-ai.com/healthz
# {"ok":true}Test vs. live mode
There is no environments table — mode is carried by the API key itself (veto_test_…
vs veto_live_…). A test key creates and reads test-mode merchants; a live key, live-mode
merchants. The two never cross: a test key resolving a live merchant gets a 404, and a
test key on a live-only route gets a 403. See Authentication.
GET /agent/checkout/{id}
Poll the full checkout session state — used to follow a held session to its resolution, or to re-read a terminal result.
Authentication
API keys, scopes, and test/live mode isolation for the Veto hosted control plane. Send your key as a Bearer token; mode is carried by the key prefix.