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.
• Application form and response lists use an opaque cursor and return data.items and data.nextCursor. See Applications for filters and the generated limit schemas.

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.

Asynchronous Roblox rank operations require an Idempotency-Key for each logical operation. Reusing that key with the same intent returns the existing operation; conflicting reuse returns 409. A 202 response confirms acceptance. Poll the operation until its outcome is known before submitting another rank change. Existing rank endpoints remain synchronous.

Application submissions allow one response per Roblox account and form version. After an uncertain response, check the applicant's status before retrying. Review decisions are final and guarded by the response revision; refresh the result after a conflict rather than blindly repeating a review.

• Retry GET requests with bounded exponential backoff for transient failures.
• Awarding a qualification already held is a no-op.
• Awarding a medal adds another occurrence even when the member already holds it. Medal removal removes one occurrence. Read the member and reconcile the count of the named medal before repeating either request after an uncertain response.
• The public API caps medal awards at 1,000 total occurrences per member. 409 medal_limit_reached requires freeing a slot rather than repeating the award.
• A duplicate blacklist create returns 409; fetch the existing entry instead of treating it as a new success.
• Before retrying any write after a timeout, fetch the target and determine whether the first call completed. There is no automatic deduplication for medal awards or removals.
• Obey Retry-After when a 429 supplies it. A scheduler queue-full response can omit it; reduce submission volume and wait for capacity before retrying.

Continue with Errors and rate limits.