Versioning and migration

Use the /v2 URL prefix for every new Clan Labs integration:

https://api.clanlabs.co/v2

The configured hostname identifies the API service. /v2 identifies the public API contract. Keep both exactly as shown.

Compatibility expectationsCopy link to Compatibility expectations

Additive response fields can appear as the product evolves. Clients should read only fields they need, ignore unknown fields, and validate required values defensively. A new operation or optional property should not require a client migration.

No public sunset date or deprecation-notice period has been announced for the legacy /users and /v1 compatibility routes. Their continued presence is not a reason to use them for new work.

Migrate a legacy integrationCopy link to Migrate a legacy integration

1. Inventory the legacy method, path, headers, inputs, and fields your integration consumes.

2. Find the equivalent generated /v2 endpoint in this reference.

3. In Settings → API Keys, rotate the migrated legacy key. Copy the new one-time cl_live_ secret.

4. Replace the legacy token and clan headers with:

   httpCopy code

   Authorization: Bearer YOUR_API_KEY
   X-Clan-Id: COMMUNITY_ID

5. Update code for the data success envelope and structured error object.

6. Add only the documented permission scopes.

7. Test reads in a non-production workflow, then test bounded writes against known targets.

8. Deploy, monitor error codes, and remove the old secret from every store.

A legacy key sent to /v2 returns 403 legacy_key_unsupported. Current keys are designed for API v2 and its audit model.

Prepare for future changeCopy link to Prepare for future change

• Keep the base URL and key in deployment configuration.
• Generate or validate types from the maintained OpenAPI document.
• Pin behavioural tests to the fields your integration uses.
• Run schema drift checks when updating the source API repository.
• Do not parse Swagger HTML or depend on undocumented legacy responses.