The Gonzo web API, for developers.

Base URL, keys and the document

• Base URL: your endpoint, over HTTPS. The server itself speaks plain HTTP and binds to the local machine by default, so a proxy supplies the HTTPS.
• Key: a person at Gonzo issues it. Send it in the header X-API-Key: gz_... or Authorization: Bearer gz_..., never in the URL and never in the body. A credential-shaped argument is refused with status 422.
• Only a hash of each key is stored. If no key is configured, the server refuses every call with 503.
• The OpenAPI 3.1 document is at /openapi.json. Add ?tiers=public_read to get the public tools only. It is generated from the same list the MCP server uses, so the two cannot drift apart.
• GET /health and GET /v1/tools need no key.

Calling a tool

A read tool is GET /v1/tools/<name> with the arguments in the query string. Any tool also answers POST /v1/tools/<name> with a JSON object body. Tools that propose something accept POST only.

curl -s -H "X-API-Key: gz_..." "https://your-gonzo-endpoint/v1/tools/roi_estimate?staff=2&hours_per_week=10&hourly_cost_usd=35"

curl -s -X POST -H "X-API-Key: gz_..." -H "Content-Type: application/json" \
  -d '{"key":"lead_response"}' "https://your-gonzo-endpoint/v1/tools/get_system"

A reply:

{ "ok": true, "tool": "get_system", "tier": "public_read",
  "source": "the product catalogue the site is built from",
  "simulated": false, "sandbox": false, "result": { "...": "..." }, "request_id": "..." }

simulated and sandbox are true when the result comes from the sandbox. An error looks like { "ok": false, "error": { "code": "...", "message": "..." }, "request_id": "..." }. No error carries a stack trace or an argument value.

Status codes

Limits

• A per-key rate limit of 60 calls a minute unless the key says otherwise, plus a throttle on repeated failed attempts.
• Body 64 KiB, arguments 16 KiB, URL 2,048 characters, a bounded number of concurrent requests.
• CORS is off unless the operator lists an origin.
• Every call, refusals included, is written to a hash-chained audit log. Arguments are stored only as a hash.

The tools

Scopes: public:read, tenant:read, tenant:propose.

The tenant tools read a simulated business: made-up people, masked email addresses, a labeled fixture for receivables, and the sandbox ad platform. No real customer appears in any of them.