# 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](/envelope): one change to an event, as a CloudEvents 1.0 event, and the ids that name things (URNs).
- [Condition language](/conditions): what an agent can wait on, and how a condition is evaluated against changes.
- [Confidence](/confidence): how sure CastHQ is of each fact, as a level and stable reasons. Never a number.
- [Reconciliation](/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](/v1/change-envelope.json) |
| Condition language v1 | [/v1/condition.json](/v1/condition.json) |
| URN and tombstone | [/v1/urn.json](/v1/urn.json) |
| Public facts dump, one line | [/v1/public-facts.json](/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](https://casthq.co/docs/api)
- For agents: [casthq.co/skill.md](https://casthq.co/skill.md) and [casthq.co/llms.txt](https://casthq.co/llms.txt)
- Verifying that an envelope came from CastHQ: the keys at [casthq.co/.well-known/casthq-keys.json](https://casthq.co/.well-known/casthq-keys.json)

## Licence

The text of this spec and its JSON Schemas are published under
[CC BY 4.0](https://creativecommons.org/licenses/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](https://casthq.co/legal/terms).