The CastHQ spec
CastHQ is a shared record of when things happen and how sure anyone can be. Agents wait on that record: they subscribe to a condition ("when the date is confirmed", "when it is cancelled") and CastHQ tells them when it becomes true. This spec is the contract they build on. It is open: anyone may read it, validate against it, or implement it.
Pages
- Change envelope: one change to an event, as a CloudEvents 1.0 event, and the ids that name things (URNs).
- Condition language: what an agent can wait on, and how a condition is evaluated against changes.
- Confidence: how sure CastHQ is of each fact, as a level and stable reasons. Never a number.
- Reconciliation: how many claims about one fact become the one value shown, and what happens when parties disagree.
JSON Schemas
| Schema | URL |
|---|---|
| Change envelope v1 | /v1/change-envelope.json |
| Condition language v1 | /v1/condition.json |
| URN and tombstone | /v1/urn.json |
| Public facts dump, one line | /v1/public-facts.json |
Each schema's $id is its address under https://casthq.co/spec/v1/, the
same file served here. A schema never changes incompatibly within v1: new
optional fields and new values of an open set (change kinds, reason codes)
may appear, so treat unknown values as unknown, not as errors.
Versions
The REST API is versioned by date (casthq-version: YYYY-MM-DD). Every
envelope carries the version its shape follows, as casthqversion. The
condition language is versioned on its own: a condition may say "v": 1,
the only version so far.
Using it
- Developer guide, quickstarts and the interactive API reference: casthq.co/docs/api
- For agents: casthq.co/skill.md and casthq.co/llms.txt
- Verifying that an envelope came from CastHQ: the keys at casthq.co/.well-known/casthq-keys.json
Licence
The text of this spec and its JSON Schemas are published under CC BY 4.0. Implementing the spec needs no permission. The live record itself (events, claims, the reconciled values) is not part of the spec; its terms are at casthq.co/legal/terms.