Versioning

Versioning

The SIPSTACK API uses a date-based version scheme. Each published revision of the API reference is stamped with the calendar date it took effect, in YYYY-MM-DD form. The current version is:

2026-06-10

That date identifies the revision of the API Reference and its OpenAPI spec — the exact set of endpoints, request/response shapes, scopes, and behaviors documented at that point in time.

How Versions Are Named

• A version is the date the revision took effect (YYYY-MM-DD), not a semantic major.minor.patch number. Dates sort naturally and read unambiguously: 2026-06-10 is newer than 2026-04-02.
• The version advances when the documented contract changes in a way worth pinning to — new endpoints, new fields, new scopes, or a behavior change.
• The /api/v2 prefix in endpoint paths (for example GET /api/v2/messages) is the URL path, not the version date. The two are independent: the path prefix identifies the route family, the date identifies the documented revision of the whole surface.

Relying on the Current Version

Today the API is not selected by a version header or URL parameter — every request is served by the current, live version, and the API Reference always describes exactly that. To build against a known contract:

• Treat the reference as the source of truth. It is regenerated from the running API, so what it documents is what the API does right now.
• Read defensively. Ignore response fields you don’t recognize rather than failing on them — additive fields can appear without a version bump.
• Pin your assumptions, not the wire format. Depend on documented fields and documented behavior (scopes, status codes, pagination shape), not on incidental ordering or undocumented fields.

Deprecation Policy

SIPSTACK does not break working integrations silently. When an endpoint, path, field, or behavior is deprecated:

1. A replacement is introduced. The new endpoint or field ships and is documented in the reference.
2. Old and new run concurrently. During a cool-down window, both the deprecated surface and its replacement are served at the same time — your existing calls keep working while you migrate at your own pace.
3. Only then is the old surface removed, after the cool-down window has elapsed and the replacement has been available the whole time.

This means a deprecation is always a migrate-then-remove sequence, never a same-day cutover. When a path is slated for change, the deprecated form and its successor coexist so no in-flight request suddenly starts failing.

Watch the changelog

Deprecations and their cool-down windows are announced in the API Changelog. Check it before relying on any endpoint you haven’t reviewed recently, and subscribe your team to notice new dated entries.

What Counts as a Breaking Change

Additive changes are not breaking and can arrive without a new version:

• A new optional request field or query parameter
• A new field in a response body
• A new endpoint, event type, or scope

Breaking changes — which always go through the deprecation cool-down above — include removing or renaming a field, tightening validation, changing a status code’s meaning, or removing an endpoint. See Error Codes for the stable error contract your client should rely on.