Versioning
Paths are unversioned today. A breaking change introduces /v2 alongside v1, which then receives only additive changes — so parse responses defensively.
Endpoint paths are unversioned today: the URL is /platform-create, not /v1/platform-create.
How a breaking change ships
When a breaking change is necessary, it will be introduced under a new prefix — /v2/platform-* — alongside the existing paths, never by changing the behavior of an existing path. The current paths will then receive only non-breaking, additive changes for at least six months after /v2 ships, giving you a window to migrate at your own pace.
Parse defensively
Because additive changes can land on the existing paths at any time, integrate so that additions never break you:
- Tolerate extra fields in responses. Read the fields you need by name; ignore the rest.
- Tolerate new
reasonstrings on existing errors. Switch on theerrorfield and treat an unfamiliarreasonas the generic case rather than failing. - Expect new optional request fields. New inputs will always be optional.
A field will never become required without a version bump
Within a version, an existing request field will never change from optional to
required, and an existing response field will never be removed or repurposed.
Any such change ships under a new /v2 path. Build to that contract and your
integration stays working across additive releases.
Request tracing & audit log
Pass your own request id to correlate logs, read how state-changing calls are audited, and why these server-to-server endpoints must never be called from a browser.
Onboarding (admin)
The admin steps that bring a platform account online — account creation, activation, key issuance, contract, and white-labelling. Done by Swarmz through support, not host-callable.