/v2/roblox-operations/ranksOpt-in asynchronous operation. Idempotency-Key is required. 202 means accepted, not completed. Unsent work expires at its deadline; sent work may reconcile afterward. Poll Location before retrying. Matching accepted intent can be replayed after losing rank-management access while the original key retains its permission and API access; new admission requires rank-management access.
members.ranks.writerank-managementapplication/jsonChange Roblox member ranks from your integration. Assigning the members.ranks.write scope requires Clan Labs Pro.
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.
| Name | Location | Type | Required | Constraints and description |
|---|---|---|---|---|
idempotency-key | header | string | Yes | pattern ^[a-zA-Z0-9._:-]{1,100}$ · Stable key for one logical operation; conflicting reuse returns 409. |
A JSON request body is required.
| Field | Type | Required | Constraints and description |
|---|---|---|---|
userId | integer | Yes | min 1, max 9007199254740991 |
roleId | integer | Yes | min 1, max 9007199254740991 |
expectedRoleId | integer | Yes | min 1, max 9007199254740991 |
deadlineSeconds | integer | No | min 5, max 3600 · Seconds until unsent work expires; defaults to 300 when omitted. Sent work may continue reconciling after this deadline. |
| Status | When it is returned |
|---|---|
| 400 | The request failed validation |
| 401 | Unauthorized |
| 403 | insufficient_scope means the API key lacks members.ranks.write. feature_unavailable means community API access is unavailable or new admission lacks rank-management access. Matching accepted intent can be replayed after losing rank-management access while the same enabled API key retains members.ranks.write and community API access. |
| 404 | Not Found |
| 409 | deduplication-conflict means Idempotency-Key conflicts with existing intent or current state. When present, Location and X-Roblox-Operation-Id identify the existing authorized operation; check it before submitting replacement intent. privacy-restricted means a current data-rights restriction prevents admission or idempotent replay. No operation metadata, Location or X-Roblox-Operation-Id is returned for privacy-restricted. |
| 429 | Rate limited or queue-full admission exhaustion. Retry-After may be absent for queue-full; retry the same Idempotency-Key with bounded exponential backoff. |
| 500 | Internal Server Error |
| 502 | Roblox rejected the community connection. Review its authorization before retrying. |
| 503 | Roblox operations are disabled or scheduling is temporarily unavailable |
This operation shares the key’s request budget. On 429, read error.code and follow Retry-After when present. A queue-full response can omit that header. Retry with bounded exponential backoff and the same Idempotency-Key. See rate limits and recovery.
Accepted with operation ID and status URL
{
"data": {
"id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "queued",
"kind": "rank",
"userId": 123,
"createdAt": "2026-10-01T00:00:00.000Z",
"deadline": "2026-10-01T00:05:00.000Z",
"result": null,
"error": null,
"statusUrl": "/v2/roblox-operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
}