Resources
Versioning & stability.
The API is versioned in the path at /v1. Within a major version, changes are additive and won't break existing integrations.
What “additive” means
| May happen within /v1 | Won't happen within /v1 |
|---|---|
| New endpoints | Removing an endpoint |
| New optional fields on responses | Removing or renaming a field |
| New standard catalog entries (scopes, events, intents) | Changing the meaning of an existing field |
| New optional request params | Making an existing optional param required |
Parse tolerantly
Ignore unknown fields rather than failing on them, and don't assume the catalog is a fixed list — new standard entries can appear at any time. This keeps your integration forward-compatible.
The catalog carries a version
The Catalog exposes a version (visible on GET /v1/catalog and getCatalog().version). It bumps as standard entries are added, so you can detect new vocabulary at runtime — see Discovery.
Deprecations
Anything that would break an integration is a new major version (a new path prefix), not a silent change to /v1. Deprecations are announced with notice and a migration window before removal.
Related
- Discover the vocabulary — read the contract, including its version, at runtime.
- Catalog — the versioned standard vocabulary.
- API reference.