API basics

Versioning

The addresses to build on, the older ones that still answer and how they announce their replacement, and what to tolerate as the API grows.

Build on these addresses

Address	Who calls it	How it authenticates
`https://api.myleadsfactory.tech/api/...`	Your servers	A secret API key (`vak_...`). See authentication.
`https://api.myleadsfactory.tech/public/v1/...`	Your own chat UI, in a browser or an app	A publishable key, then a conversation token. See build your own chat UI.

The developer API's URL carries no version number; the public chat API's is v1. The chat widget calls its own routes under /public/chat, with the same conversations; call /public/v1 from your own code. Every reference page and the OpenAPI file describe these addresses as they are served today.

Older addresses

Integrations written before the current layout used /v1/... for the API and /chat/... for web chat. Both still answer, and every response from them says where to move:

Response headers

Deprecation: true
Link: </api/calls>; rel="successor-version"

Old	New
`/v1/<resource>` with an API key	`/api/<resource>`, where the developer API serves it
`/chat/<path>`	`/public/chat/<path>`

A /v1 route that has no place on the developer API (API key management, for example) sends Deprecation: true without a Link. Those routes are console-only and should not be called with a key.

The old addresses share rate limits with the new ones, so moving changes nothing about your budget.

Build to tolerate growth

The API gains fields, values and events over time. Write clients that keep working when it does:

Ignore fields you do not know. Responses and webhook payloads gain fields; never fail on an extra key.
Expect new values in enums. A status, ended_reason or source can gain a value. Handle the ones you know and give the rest a default path.
Expect new webhook events. A subscription with no events filter receives every type in its mode, including ones added later. Acknowledge unknown types with a 2xx and move on. See webhook events.
Treat ids, cursors and tokens as opaque strings. Their prefixes (asst_, call_, ct_) help you read logs, but do not parse what follows.

Webhook payload version

Every webhook body carries "schema_version": "1.0". Check it if you want to know the envelope a delivery was built with; today every event is version 1.0.