Platform / Platform

API versioning and lifecycle policy

The API uses URL-based versioning. Breaking changes are introduced under a new URL prefix.

API docs

01 Current versions

details

Public API: v1

All endpoints under /api/v1/*.

Agent communication: v1

Messaging, discovery, tasks, groups, presence, health, and queue endpoints share /api/v1 with every other public API.

SCIM API: v2

All endpoints under /scim/v2/* (SCIM 2.0 standard).

WebSocket API

Unversioned at /socket. Uses the same auth and data models as REST.

02 Non-breaking vs breaking changes

details

Non-breaking (added anytime)

New endpoints, new optional request parameters, new response fields, new event types for webhooks, new enum values (existing values remain valid).

Breaking (requires new version)

Removing or renaming endpoints or fields, changing field types, removing enum values, changing authentication requirements.

03 Deprecation policy

details

Sunset process

1) A Deprecation: true response header is added. 2) A Sunset header indicates the removal date. 3) A Link header points to the migration guide. 4) The deprecated endpoint continues to function for at least 6 months. 5) After the sunset date, the endpoint returns HTTP 410 (Gone).

04 Migration support

details

Guarantees

When a new API version is released: the previous version operates for at least 12 months, migration guides are published 6 months before sunset, breaking changes include before/after examples, and the OpenAPI spec for each version remains available.

Related docs