---
title: "API"
source: "docs/api/README.md"
---

> Part of [API](/api/llms.txt). Every page: [llms.txt](/llms.txt).
> View: [API reference](/api/reference.html)

# API

The contract between the apps and the backend is [`openapi.yaml`](/api/openapi.yaml) (the client API, used by `ios/`)
and [`openapi-admin.yaml`](/api/openapi-admin.yaml) (the admin API, used by `dashboard/`). They are the source: the
backend answers every operation in them, and the iOS and web clients are built against them. These docs link the
files as they are. Both are binding (`README.md`, "Source of truth"); `.redocly.yaml` holds the lint rules.
[`reference.html`](/api/reference.html) renders both with Redoc, in the local docs site (`pnpm docs:dev`) and the hosted one.

## Rules

- A contract change edits `openapi.yaml` (or `openapi-admin.yaml`) in the same PR as the code and is called out in
  the PR description, with both sides updated. Every track that reads the changed part gets a follow-up task.
- Errors use the `ErrorEnvelope` schema: a code, a message localized for the request's `Accept-Language`, whether the
  client may retry, and the stage. Every request carries `Accept-Language: <UI locale>` (ADR-001 D13).
- Example responses for the screens live in `examples/en/` and `examples/zh-Hans/` (served with the design module), one
  copy per locale (API-shaped seed data behind every number on a board, written by `design/tools/build.py`).
  `examples/index.json` names each file's operation (or request body, or schema), and
  `pnpm design:check` (botgumi's `botgumi-design check`) validates every copy against this contract.
  `ios/scripts/validate_fixtures.py` checks the iOS fixtures made from them.
- Fields the screens need but the contract lacks are listed as contract change requests at the top of
  `design/data-binding.md`, each with its fallback until merged: CCR-1 to CCR-13 are applied, CCR-14 (error responses
  on the reads) is open.

## Endpoints

One line per operation lives in the contract itself (`operationId`, method and path, tags). The screens that call
each operation are listed per screen in `design/hifi/<ID>/screen.md` ("Reads and calls") and in `design/flows.md`.