Machine-Readable Specs

Everything on this site is backed by two machine-readable specifications. They are the source the narrative pages and the generated REST API (OpenAPI) reference are checked against — and the input you feed a code generator to get a typed client in minutes.

The two documents

Spec	Covers	File
OpenAPI 3.1	the REST Bot API — every endpoint, request, and response	`openapi.yaml`
AsyncAPI 3.1	the two ndjson event streams and their message payloads	`asyncapi.yaml`

The rendered REST reference in the sidebar (REST API (OpenAPI)) is generated from openapi.yaml at build time, so it can never drift from the file you download.

Generate a REST client

The OpenAPI document works with any generator. A few starting points:

# TypeScript types (openapi-typescript)
npx openapi-typescript https://jc.id.lv/dicechess-play-api/openapi.yaml -o dicechess.d.ts

# A full client in any language (openapi-generator)
openapi-generator-cli generate \
  -i https://jc.id.lv/dicechess-play-api/openapi.yaml \
  -g python -o ./dicechess-client

# Interactive browsing / try-it-out
npx @scalar/cli reference https://jc.id.lv/dicechess-play-api/openapi.yaml

Prefer a ready-to-run starter over generating from scratch? Two MIT-licensed “Use this template” bots build on these contracts — clone and run in a minute:

dicechess-bot-python — dependency-free Python.
dicechess-bot-typescript — zero-dependency TypeScript.

See Licensing for Bots for how they are licensed.

Browse the event streams

The ndjson streams are documented narratively under Event Streams. For the machine-readable version, download asyncapi.yaml and open it in AsyncAPI Studio, or render it locally:

npx @asyncapi/cli start studio -f asyncapi.yaml