Public contract versioning
Understand what the version v1 represents, which enrichments a client should tolerate, and which changes instead constitute a contract break from a consumer's perspective.
The public REST boundary is /v1
Public REST resources are exposed under https://api.ormuz.io/v1/. This prefix identifies the HTTP contract family consumed by your integration; it corresponds neither to a process revision, an extension version, an Agent revision, nor a Decision revision.
A Process revision, Agent revision, or Decision revision freezes the behavior of a deployable artifact. /v1 describes the shape of the machine interface used to create, read, or execute those artifacts.
Distinguish enrichment from breaking change
| Evolution | Impact consommateur | Recommended behavior |
|---|---|---|
| New optional field in a response | Enrichissement | Ignore unknown fields your client does not use. |
| New endpoint or resource | Enrichissement | No impact while your integration does not call it. |
| New event type | Catalog enrichment | Subscribe explicitly to the types you need rather than all events. |
| New enum value | May surprise a closed client | Provide an “unknown value” branch when the enum represents a provider or extensible state. |
| Field removed, renamed, or made required | Breaking for clients that depend on it | Do not treat this change as a compatible enrichment. |
| Field type, unit, or semantics changed | Contract break | Treat as a version change or explicit migration. |
| Event identifier renamed | Filtering break | Explicitly update affected subscriptions and consumers. |
Identifiers, pagination cursors, tokens, and provider references must be treated as opaque values. A client that depends on their internal structure creates its own incompatibility.
Event compatibility
Type identifiers — for example invoice.paid or extension.stripe.payment_intent.succeeded — are the public filtering key. An event payload is a snapshot; it may be enriched with new public fields without your consumer needing to know them.
- Ignore unknown fields.
- Do not assume a global order across all event types.
- Reread the current object through the API when a decision depends on its current state rather than the snapshot alone.
- Use explicit subscriptions in production when your handling depends on a precise contract.
The event catalog is the reference for platform types; each extension documents its own events in its integration section.
Build a robust client
- JSON responses: read the fields you need and ignore the rest.
- Enums : provide safe behavior for an unrecognized value instead of treating it as success.
- Pagination: use
has_moreor the documented cursor, without fabricating the next cursor. - IDs : store them as opaque strings.
- Amounts: respect
common.amountand the associated currency; do not convert to floating point. - Dates : preserve ISO 8601 timestamps with timezone and distinguish a civil date from a datetime.
Artifacts have their own versioning
Processes, Forms, Agents, and Decisions use immutable revisions to ensure an execution can be traced to the exact configuration that produced it. This mechanism is independent from the HTTP version.
| Concept | Frozen version | Documentation |
|---|---|---|
| Process | Process revision | Definitions, revisions, and instances |
| Form | Form revision | Forms |
| Decision | Decision revision | Decisions |
| Agent | Agent revision | Agents |
Track the current contract
The API reference, the event catalog and integration pages are the up-to-date public sources for the current contract. Structural documentation catalogs are generated from product registries so a newly exposed endpoint, node, or event does not depend on an incomplete manually maintained list.
When updating an integration, compare the fields and types your application actually consumes against the current contract. A change in their meaning must be treated as an explicit migration even when the JSON remains syntactically valid.