Versioning, deprecation and rate limits

Versions

The public API lives under /api/v1 (https://api.vaakyo.com/api/v1/...). Build integrations against v1 only: the unversioned /api/... paths are what the console uses and can change with it.

Within v1 we only make additive changes, without notice:

• new endpoints and new optional request fields;
• new fields in responses (ignore fields you don’t know);
• new values in enums such as call statuses and webhook event types (handle unknown values);
• new response headers.

Anything else is breaking: removing or renaming an endpoint or field, making an optional field required, changing a field’s type or meaning, or tightening validation. Breaking changes go into a new version (v2), or follow the deprecation process below.

Deprecation

When something in v1 is going away:

1. It is announced in the changelog and by email to workspace owners.

2. From that day, every response of the affected operation carries these headers:

   Header	Example	Meaning
   Deprecation	@1790812800	When it was deprecated, as a Unix time (RFC 9745)
   Sunset	Thu, 01 Apr 2027 00:00:00 GMT	When it stops working (RFC 8594)
   Link	<https://docs.vaakyo.com/versioning>; rel="deprecation"	Where to read what to use instead

3. It keeps working for at least 6 months after the announcement, until the Sunset date.

Log or alert on the Deprecation header in your client to catch these early. Nothing is deprecated today.

Rate limits

API keys and connected apps are limited per key, in one-minute windows (120 requests a minute unless your plan or agreement says otherwise). Every /api response states the policy, and keyed responses show where you stand:

Header	Example	Meaning
RateLimit-Policy	"per-key";q=120;w=60	The quota (q) per window of w seconds (IETF RateLimit fields)
RateLimit	"per-key";r=87;t=23	Requests left (r) and seconds until the window resets (t)
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset	120, 87, 23	The same, in the earlier draft’s form
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset	120, 87, 1791581640	The same; the reset is a Unix time

Over the limit you get 429 Too Many Requests with a Retry-After header (seconds): wait that long, then retry. Spread bulk work out, or use batches for many calls, which the platform paces for you.

Time zones

Every v1 response formats timestamps in Asia/Kolkata unless you pass ?timezone= (or the X-Timezone header) with an IANA name; the zone used comes back in X-Timezone. See Authentication.