Skip to main content

API overview

The GrinGo API is a single Hono app running on Cloudflare Workers. Every route is versionless — there is no /v1 prefix. Auth is Privy JWT on every non-webhook endpoint.

Base URLs​

EnvironmentURL
Local devhttp://localhost:8787
ProductionSet by Cloudflare Workers deploy — TBD DNS

Auth​

All non-webhook routes require:

Authorization: Bearer <privy access token>

The token is verified against Privy's JWKS. See architecture/auth for the full model.

Content type​

  • Requests: application/json (Zod-validated via @hono/zod-validator).
  • Responses: application/json.

Errors​

  • 4xx — validation, auth, business rules. Body: { "error": "<user-facing message>" }. Zod validation errors return 400 with zod-validator's default shape.
  • 5xx — internal / upstream. Body: { "error": "<message>" }.
  • Bridge upstream failures surface as 502 with a generic message; details are logged server-side.

Rate limiting​

Not implemented at the API layer. Cloudflare's default DDoS protection applies.

Route index​

Full request/response shapes in endpoints. Webhook contract in webhooks.