Versioning
How /v1 evolves, what counts as breaking, and how we retire a path.
Everything hangs off /v1. That prefix is the contract: a client written against today's endpoints keeps working without a rewrite.
What can change on /v1
Additive changes land here. A new endpoint, a new optional field, a new error code. Existing fields keep their meaning, required fields stay required, and a client that ignores what it does not know keeps working.
What does not happen on /v1
A breaking change gets a new prefix (/v2), not a silent rewrite of /v1. Breaking means: removing or renaming a field, changing a type, turning an optional field required, or changing the meaning of a code.
There is no /v2 today. When there is, /v1 stays up long enough to migrate, and the two prefixes are documented side by side.
Deprecation
Nothing is deprecated today.
When a path or a field is going away we will:
- Mark it in the OpenAPI spec (
deprecated: true). - Say so on this page, with the replacement.
- Send a
Sunsetheader (an HTTP date) on responses that still serve the old path, so a client can see the deadline without reading the docs.
Until that happens, do not treat /v1 as unstable. Additive growth is the point of the prefix.
Keys are not versioned
An organization API key works on whichever prefix is current. You do not mint a new key to keep using /v1, and a key is not scoped to a version.
Rate limits
How much you can ask for, what a 429 looks like, and how to back off.
Push a lead POST
Creates the person (or reuses them, matched by phone or email) and their enquiry, in one call. Idempotent per `externalId` within your organization. A lead with a phone number and no conversation yet is what the automatic first contact reacts to: if the organization has it enabled, the approved template goes out on its own.