API v2 · Members

Suspend a member

POST/v2/members/{userId}/suspensions

Last updated 1 October 2026

Overview

Claims the suspension before changing Roblox and verifies the resulting role. A member may hold only one active suspension. An unresolved scheduled write returns 504 with an operation status Location and retains the active claim; do not retry before checking that operation.

Permission scope: members.suspensions.write
Community feature: suspensions
Content type: application/json

Authentication

Send Authorization: Bearer YOUR_API_KEY and X-Clan-Id: COMMUNITY_ID. The community API switch and key must be enabled. The key must have the scope shown above. See authentication and key storage.

Parameters

Name	Location	Type	Required	Constraints and description
`by`	query	`userId \| username`	No	How to interpret the identifier in the path. Prefer `username`: under Roblox's scoped user identifiers an in-experience user id is not a global one.
`userId`	path	`string`

Request body

A JSON request body is required.

Field	Type	Required	Constraints and description
`durationMs`	`integer`	Yes	min 1, max 9007199254740991
`reason`	`string`	Yes	min length 1, max length 1024

Error responses

Status	When it is returned
400	The request was malformed or failed validation.
401	The API key is missing, malformed, or not recognised for this community.
403	The API key is disabled, lacks the required permission (insufficient_scope), or the community's subscription or tier does not cover API access or this feature (feature_unavailable). These admission-time failures create no new operation. actor-authorization-revoked additionally means the API key, its required permission, the community API switch or API-access entitlement was revoked before dispatch. Restore authorization before retrying. This response has no operation status headers or reference.
404	The requested resource does not exist.
409	The request conflicts with current state. deadline-cancelled-before-dispatch confirms the unsent operation was cancelled at its deadline. When present, status headers identify the operation; check its cancellation or failure before retrying.
429	Rate limited, queue-full admission exhaustion, or provider-rejected-429 when Roblox rejects a scheduled attempt for throttling. queue-full means no new operation was admitted. Retry-After may be absent; honor it when supplied and use bounded backoff. When Location or X-Roblox-Operation-Id is present, check that operation before repeating a synchronous write; otherwise inspect current Roblox resource state before retrying.
500	Unexpected server error.
502	Roblox authorization failed or the provider returned an upstream error. Review the connection before retrying. When present, status headers identify the failed operation; a pre-admission failure may have no operation.
503	Roblox scheduling or its budgeted live-state read is unavailable. A failed pre-admission read creates no job.
504	A Roblox request timed out or has an unresolved outcome. With scheduling enabled, outcome-pending-check-status and provider-rejected-408 include Location and X-Roblox-Operation-Id only when current access to the frozen operation is verified; check authorized status before retrying. Revoked or unverifiable access omits references while retaining the pending outcome. The reference identifies the saved operation; status reports whether it remains pending or is terminal. With scheduling disabled, roblox_cloud_timeout has no operation or status headers. A timeout does not confirm success or failure; check the member's Roblox state before repeating a write without an accessible reference.

Server-side examples

After HTTP requests are enabled, Roblox Lua uses HttpService:GetSecret() from a server Script, never a LocalScript.

Request

POST

curl --request POST \
  --url 'https://api.clanlabs.co/v2/members/1234567/suspensions?by=userId' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-Clan-Id: COMMUNITY_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "durationMs": 1,
  "reason": "YOUR_REASON"
}'

Response

201

The created suspension

{
  "data": {
    "status": "active",
    "target": {
      "name": "PixelComet482",
      "id": 1234567,
      "redacted": false
    },
    "invoker": {
      "name": "PixelComet482",
      "id": 1234567,
      "redacted": false
    },
    "reason": "Misconduct",
    "durationMs": 86400000,
    "expiresAt": 1735689600000,
    "restoredAt": "YOUR_RESTORED_AT",
    "cancelledAt": "YOUR_CANCELLED_AT",
    "previousRank": {
      "uniqueId": 1,
      "id": 1,
      "name": "EXAMPLE_NAME"
    },
    "suspendedRank": {
      "uniqueId": 1,
      "id": 1,
      "name": "EXAMPLE_NAME"
    },
    "createdAt": 1735689600000,
    "lastUpdatedAt": 1735689600000
  }
}

Suspend a member | Clan Labs API

OverviewCopy link to overview

AuthenticationCopy link to authentication

ParametersCopy link to parameters

Request bodyCopy link to request body

Error responsesCopy link to error responses

Rate limitsCopy link to rate limits

Related endpointsCopy link to related endpoints

Response

Overview

Authentication

Parameters

Request body

Error responses

Rate limits

Related endpoints