API reference¶

gorge has four public interfaces. You can watch and play games over HTTP with a live event stream, plug in agents and harnesses over SpellBench v2, or import gorge as a Go library. This section is the authoritative reference for each one: every endpoint, message and signature, the versioning rule that applies, and the machine-readable files that client generators can consume. The tutorials elsewhere on the site link here for detail; start with Bots or the User's guide if you want a walkthrough.

Which API for which job¶

flowchart LR
  subgraph you["what you are building"]
    A["a viewer, dashboard<br/>or replay tool"]
    B["a bot in Python, Java, JS…<br/>playing one seat"]
    C["a SpellBench agent<br/>or benchmark harness"]
    D["a Go program: custom bot,<br/>own server, test harness"]
  end
  subgraph gorge["gorge"]
    H["gorged HTTP API<br/>JSON + SSE"]
    S["SpellBench v2<br/>NDJSON over stdio"]
    G["Go packages<br/>engine/*, bots, server/*"]
  end
  A -- "GET views, events;<br/>GET /api/stream" --> H
  B -- "GET pending /<br/>POST intent" --> H
  C -- "spawns spellbench-gorge-env,<br/>or gorged -sb-agent spawns it" --> S
  D -- "import" --> G

You want to…	Use	Reference
Show tables, boards and transcripts live	HTTP and the SSE stream	HTTP API, Event stream
Decode stream frames or view JSON in another language	The wire types	Wire protocol, `gorge-protocol.schema.json`
Play a seat from any language	`pending` / `intent` over HTTP	HTTP API: the decision loop, walkthrough in Playing a seat over HTTP
Run gorge as the engine behind a SpellBench host, or seat a SpellBench agent at a gorge table	SpellBench v2	SpellBench v2
Write a bot in Go, embed the engine, or run your own server	The Go packages	Go embedding API

All four sit on one engine contract. The engine asks a decision that lists every legal option, and the player answers with an intent naming option indices. No rules knowledge crosses any of these boundaries, and the engine validates every answer. A client of any API can play badly, but never illegally.

Versioning and compatibility¶

Each surface states its rule in the code. The table gives the rule, and says what enforces it and what is only a convention.

Surface	Version marker	Rule	Enforced by
HTTP API and stream frames	`protocol.Version` = 1, the `v` field of every frame. No URL prefix.	The version bumps only on a breaking change to a body. Additive fields do not bump it, so clients ignore unknown fields.	The shape is pinned by `TestGoldens` (server/protocol), `TestOpenAPISchemasMatchGo` and `TestCommittedProtocolTSIsFresh`; each fails on any wire change until its artifact is regenerated. The route set is pinned by `TestOpenAPIRoutesMatchSpec`. The bump itself is a convention: no test tells breaking from additive.
Decision kinds	the closed `decision.Kinds` set (13)	A new kind is a new case for every client	`TestOpenAPISchemasMatchGo` compares the spec's enum with `decision.Kinds`; `TestKindsListsEveryKindOnce` (engine/decision)
Event kinds	`events.Kind`	Append-only: kinds are added at the end and existing ordinals never move	The golden replay heads (`TestHeads`, `TestRepoDeckGamesReplayExactly` in engine/rules)
SpellBench	protocol string `spellbench/v2`; `protocol_minor` (gorge answers 0)	Any other protocol string is `protocol_mismatch`. New features arrive as `x_` extensions.	The request decoder (`server/spellbench/protocol`), the goldens in `server/spellbench/testdata/goldens`, and `TestSemanticSchemaMatchesKindTable` / `TestSchemaErrorCodesMatchErrorsGo` for the published schemas
Go packages	none: the module has no release tags	Any commit may change an exported signature. Pin a commit.	Nothing, beyond the import-layering tests in `internal/archtest` and the `server/host` contract harnesses (`RunContractTable` and friends) that embedders can run in their own tests. See Go: Stability.
ManaBrew adapter	`/api/manabrew/v0/`	Deprioritised; not part of this reference	its own tests under `-tags manabrew`

gorge has no contract registry and no deprecation process. When a surface changes, the commit that changes it regenerates the artifacts above, and that diff is the changelog.

Machine-readable files¶

Everything below is published with the site, next to this page, so a generator can fetch it by URL (https://adams-shaun.github.io/gorge/api/<file>):

File	Format	Covers	Generated from
`openapi.json`	OpenAPI 3.1 (JSON Schema 2020-12 dialect)	Every gorged HTTP operation, schema and real example	Routes and examples written by hand; `x-go-type` schemas generated from Go source. Guarded by `server/host/httpapi/openapi_test.go`.
`openapi.yaml`	The same, as YAML		Rendered from `openapi.json` by the same test
`schemas/gorge-protocol.schema.json`	JSON Schema 2020-12	The host-client wire types, `$defs` (validate a frame against `#/$defs/StreamFrame`)	Rendered from `openapi.json`'s components by the same test
`schemas/spellbench-v2/*.schema.json`	JSON Schema 2020-12	SpellBench v2 requests, responses, observation, candidate kinds	Written by hand. Kinds, vocabularies and error codes are guarded by `server/spellbench/protocol/schema_doc_test.go`.
`web/src/protocol.ts`	TypeScript	The wire types, for the web client	`cmd/gentypes` (`make gentypes`)

To generate a client, point your generator at openapi.json. For example, with openapi-generator (not run for this page):

openapi-generator generate -i https://adams-shaun.github.io/gorge/api/openapi.json -g python -o gorge-client

The stream is Server-Sent Events, which OpenAPI 3.1 can only describe as a text/event-stream response. Generated clients will not parse it for you. Read the frames as StreamFrame (see Event stream).