Overview
Opt-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.
- Permission scope
members.ranks.write- Community feature
rank-management- 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 |
|---|---|---|---|---|
idempotency-key | header | string | Yes | pattern ^[a-zA-Z0-9._:-]{1,100}$ · Stable key for one logical operation; conflicting reuse returns 409. |
Request body
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. |
Error responses
| 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. member-review-required means an earlier request for this member needs administrator review and this new request was not submitted. 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 member-review-required or 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 |
Rate limits
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.