Requests, responses, pagination, and retries

API v2 accepts JSON for request bodies and returns JSON for responses unless an endpoint documents an empty success body.

Request validationCopy link to Request validation

Send Content-Type: application/json for JSON bodies. The generated endpoint page marks required fields and reports types, enums, length limits, numeric bounds, formats, and array limits. Many write schemas reject undeclared fields.

Do not coerce arbitrary user input into a request. Validate it before calling Clan Labs and preserve the API’s structured validation issues for debugging without logging private data.

Successful responsesCopy link to Successful responses

A single resource or result is wrapped in data:

{
  "data": {
    "id": "RESOURCE_ID"
  }
}

Collection responses can add meta:

{
  "data": [],
  "meta": {
    "nextCursor": null
  }
}

Treat undocumented fields as unstable and do not assume a property omitted from one response is always absent.

PaginationCopy link to Pagination

Pagination is endpoint-specific:

• GET /v2/members uses limit from 1–100, defaults to 50, and returns meta.nextCursor. Pass that value as the next cursor.
• GET /v2/events uses a UUID cursor, a 1–100 limit that defaults to 25, and optional status.
• GET /v2/warnings uses limit from 0–200, defaults to 50, and skip from 0.

Stop when nextCursor is absent or null, or when an offset page contains no more records. Do not modify or infer a cursor.

Filtering and orderingCopy link to Filtering and ordering

Supported filters are listed on each operation. Current examples include blacklist type, warning targetId, targetUsername, and severity, and event status.

API v2 does not expose a general sort parameter. Preserve the endpoint-defined order; sort a copy in your own application only when that does not break cursor pagination.

Identifying membersCopy link to Identifying members

For a {userId} path, send a global Roblox user ID, or send a Roblox username and add ?by=username. The member fetch also supports refresh=1 or refresh=true to bypass its staleness window, sync from Roblox, and run the configured AutoRank check. Use refresh deliberately because it performs more work than a cached read.

Idempotency and retriesCopy link to Idempotency and retries

There is no global Idempotency-Key support in the current API.

• Retry GET requests with bounded exponential backoff for transient failures.
• Awarding a medal or qualification already held is explicitly a no-op and can be reconciled safely.
• A duplicate blacklist create returns 409; fetch the existing entry instead of treating it as a new success.
• Before retrying any other write after a timeout, fetch the target and determine whether the first call completed.
• Obey Retry-After on 429.

Continue with Errors and rate limits.