Proposal, not live spec. How the API reference could be structured, drawn from Stripe
and Plaid. For team review once the API exists.
Generate from OpenAPI 3.1 (single source of truth)
The strongest pattern across the best docs: keep one OpenAPI 3.1 spec in the repo and generate the reference from it - never hand-write endpoint pages. This is how the reference stays in sync with the real API (no drift). Mintlify renders it natively; the spec also lets partners generate their own SDK clients.Proposed endpoint groups
| Group | Purpose |
|---|---|
| Quotes | Get a quote for a deposit (route, fees, min/max) |
| Deposits | Create a deposit and read its status |
| Coverage | Fetch supported chains, tokens, funding sources |
| Webhooks | Manage webhook endpoints |
Anatomy of a good endpoint page (Stripe / Speakeasy)
- Method + URL at the top (
POST /deposits) - Parameters split by type (path / query / body / header), each with type + required + description
- Request example with real values, not placeholders
- Response example for success and error
- Error codes with “why it happened” and “how to fix”
- An interactive “Try it” playground (Mintlify provides this)
Authentication section
Three things, in order: how to get the key, how to pass it on a request (exact header format), and key rotation / expiry.Keep it in sync (light CI)
OpenAPI spec in repo + a linter (vacuum / Spectral) + oasdiff on breaking changes as a
PR comment. Cheap to set up, prevents the reference from rotting.