> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rheon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Proposal: API reference

> OpenAPI as source of truth, endpoint groups, and page anatomy.

<Info>
  **Proposal, not live spec.** How the API reference could be structured, drawn from Stripe
  and Plaid. For team review once the API exists.
</Info>

## 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.