Skip to content
Clan LabsAPIv2
GuidesWebsite Open dashboard
OverviewAuthenticationAPI keysRequestsErrorsMigrationEndpoints
API reference
API v2
  • API overview
  • Authentication
  • API keys and scopes
  • Requests and responses
  • Errors and rate limits
  • Versioning and migration
  • Swagger migration
Troubleshooting
  • Authentication failures
  • Request and rate-limit errors
Members
  • GETList members
  • GETFetch one member
  • POSTChange a member's experience
  • POSTChange a member's quota points
  • PUTSet a member's rank
  • POSTPromote a member one rank
  • POSTDemote a member one rank
  • POSTAward a medal
  • DELETERemove a medal
  • POSTAward a qualification
  • DELETERemove a qualification
  • GETList a member's suspensions
  • POSTSuspend a member
  • POSTRestore a member's active suspension
  • POSTCancel a member's active suspension
Configuration
  • GETList ranks
  • GETFetch one rank
  • GETList medals
  • GETFetch one medal by name
  • GETList qualifications
  • GETFetch one qualification by name
Moderation
  • GETList blacklist entries
  • POSTCreate a blacklist entry
  • GETFetch one blacklist entry
  • PATCHUpdate a blacklist entry's description
  • DELETERemove a blacklist entry
  • GETList warnings
  • POSTIssue a warning
  • GETFetch one warning
  • PATCHUpdate a warning
  • DELETEDelete a warning
Events
  • GETList events
  • POSTCreate and announce an event
  • GETList curated event types
  • GETList approved event locations
  • GETFetch one event
  • POSTCancel an event
  • POSTFinish an event
  • POSTCreate a fresh Discord announcement
GuidesClan Labs websiteOpen dashboard Support
API v2
  • API overview
  • Authentication
  • API keys and scopes
  • Requests and responses
  • Errors and rate limits
  • Versioning and migration
  • Swagger migration
Troubleshooting
  • Authentication failures
  • Request and rate-limit errors
Members
  • GETList members
  • GETFetch one member
  • POSTChange a member's experience
  • POSTChange a member's quota points
  • PUTSet a member's rank
  • POSTPromote a member one rank
  • POSTDemote a member one rank
  • POSTAward a medal
  • DELETERemove a medal
  • POSTAward a qualification
  • DELETERemove a qualification
  • GETList a member's suspensions
  • POSTSuspend a member
  • POSTRestore a member's active suspension
  • POSTCancel a member's active suspension
Configuration
  • GETList ranks
  • GETFetch one rank
  • GETList medals
  • GETFetch one medal by name
  • GETList qualifications
  • GETFetch one qualification by name
Moderation
  • GETList blacklist entries
  • POSTCreate a blacklist entry
  • GETFetch one blacklist entry
  • PATCHUpdate a blacklist entry's description
  • DELETERemove a blacklist entry
  • GETList warnings
  • POSTIssue a warning
  • GETFetch one warning
  • PATCHUpdate a warning
  • DELETEDelete a warning
Events
  • GETList events
  • POSTCreate and announce an event
  • GETList curated event types
  • GETList approved event locations
  • GETFetch one event
  • POSTCancel an event
  • POSTFinish an event
  • POSTCreate a fresh Discord announcement
  1. API reference
  2. /
  3. API v2
API v2

Versioning and migration

Target API v2, move migrated legacy keys safely, and avoid dependencies on retired surfaces.

Last updated 3 September 2026

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

text
https://v3.api.clanlabs.co/v2

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

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.

There is no verified public sunset date for the legacy /users and /v1 compatibility routes. Their continued presence is not a reason to use them for new work. No formal future deprecation-notice window could be confirmed in the implementation, so this site does not invent one.

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:

    http
    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 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.

For the documentation transition, read Swagger migration.

PreviousErrors and rate limitsNext Swagger migration
On this page
  1. Compatibility expectations
  2. Migrate a legacy integration
  3. Prepare for future change