Trovacast

Platform

Versioning

The version is in the path. Within v1 every change is additive, so an integration written today keeps working.

  • The version is in the path: /v1.
  • Within v1, changes are additive only: new endpoints, new optional request fields, new response fields, new enum values, new event types and new error codes.
  • Your client must ignore fields it does not know, accept enum values it does not know, and read an error code it does not know by its HTTP status.
  • Removing or renaming a field, endpoint or error code, tightening validation, or changing a meaning is a breaking change and ships as /v2, with v1 kept running for a published deprecation period.

Security fixes may tighten a default

One exception, stated plainly: a security or safety fix may tighten a default or a requirement inside v1 when leaving it open would put you, your contacts or the platform at risk — waiting for /v2 would leave the risk open for every integration. On 2026-11-06, for example, calls began to reach the home market (+91) only by default: a call anywhere else is 422 DESTINATION_BLOCKED until we open that country for your organization, where before every country but +1 was dialled. Such a change is always in the changelog under Changed, marked “a changed default” or “a tightened requirement”, with the error code you will now meet and what to do about it — and, whenever it can wait, announced in the console and by email to your organization’s owners before it ships.

Enum casing

Most values are lower case (whatsapp, toll_free, in_progress, openai). A few request fields kept the upper case they were first published with — a call’s mode (EXTERNAL_AGENT, AI_AGENT, …) and purpose, consent source (WEB_FORM, …) and a WhatsApp template’s category (UTILITY, …). Those, the AI agent fields (voice.provider, kind, …) and a subaccount key’s mode (test or TEST, as GET /v1/me answers it), accept either case — ai_agent or AI_AGENT — so nothing you already send breaks. The contract lists both spellings, the documented one first; a response always answers in its documented spelling.

The contract

GET /v1/openapi.json is the machine-readable contract — unauthenticated, in every environment. The API reference, the SDKs and the Postman collection are generated from it, and a check fails our build when they drift apart.

Every change is recorded in the changelog.