# Raw specs

The specs are the contract. Everything on this site is written against them: if
a page and the spec disagree, trust the spec — and if the spec and the running
API disagree, trust the API.

| Document | Covers | Download |
| --- | --- | --- |
| **OpenAPI 3.1** | The REST surface | [`openapi.yaml`](https://docs.troncharts.xyz/docs/openapi.yaml) |
| **AsyncAPI 2.6** | WebSocket frames + outbound webhook payloads | [`asyncapi.yaml`](https://docs.troncharts.xyz/docs/asyncapi.yaml) |

`openapi.yaml` is hand-maintained, not generated from the routes, and it does
not yet document every `/api/v1` path. Treat a missing path as undocumented,
not as absent — check the running API before concluding an endpoint doesn't
exist.

## Generate a client

```bash
curl -sO https://docs.troncharts.xyz/docs/openapi.yaml

npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g typescript-fetch -o ./generated
```

Any generator that reads OpenAPI 3.1 works — Python, Go, Rust, Java. The spec
is also directly importable into Postman and Insomnia.

## Discover at runtime instead

If you'd rather not parse a spec, `GET /api/v1/discovery` returns plain JSON in
one round-trip: a curated index of the most-used endpoints with the credential
tier each needs, the WebSocket streams, and usage notes. It reads no session.

It is an index, not the whole surface — roughly forty endpoints against the
spec's hundred-plus. Firms, reports, routing (`/sor`), indicators and referrals
are in `openapi.yaml` only, so parse the spec when you need the complete
contract. See [Base URLs & discovery](https://docs.troncharts.xyz/docs/start/base-urls/).

## Versioning

The REST surface is versioned in the path (`/api/v1/*`). Additive changes —
new endpoints, new optional fields — ship without a version bump, so build
clients that ignore unknown fields rather than rejecting them.

Which venues are wired and which symbols trade are **deployment** properties,
not API-version properties. They change without notice, which is why the
[discovery endpoints](https://docs.troncharts.xyz/docs/start/base-urls/#dont-hardcode--discover) exist.