## API reference

This page is the developer entry point for Brothh API documentation. Use it to explain request conventions, resource naming, error handling, pagination, ID formats, and where readers should go next for product-specific guides.

{% figure src="/docs-images/gitbook-developers-api.png" alt="GitBook API reference page" caption="The API reference page is the main public docs entry for request conventions, authentication expectations, and playground-linked examples." /%}

## Authentication

API examples should use bearer-token language, but they must stay honest about the current gate: server-side secret-key issuance is not generally available in GitBook yet. Do not show a live secret reveal flow until the Convex schema and API support it. When publishable keys are available, render them with viewer variables so anonymous readers never see another account's values.

## Request conventions

Document HTTP method, path, required headers, content type, idempotency expectations, and common error shapes near the first example. Prefer short cURL examples paired with the expected response shape. If an endpoint is planned, label it as planned instead of presenting it as live.

## Playground

Use the Markdoc \`\\{% playground endpoint="listProducts" method="GET" path="/v1/products" /%\\}\` tag when embedding examples that should route through the docs playground proxy. The playground must call GitBook's proxy first, never the production API directly from the browser. Until the proxy can inject account secrets server-side, the playground may show a signed-in gate or unavailable state.