Skip to content
Clan LabsAPIv2
GuidesWebsite Open dashboard
OverviewAuthenticationAPI keysRequestsErrorsMigrationEndpoints
API reference
API v2
  • API overview
  • Authentication
  • API keys and scopes
  • Requests and responses
  • Errors and rate limits
  • Versioning and migration
  • Swagger migration
Troubleshooting
  • Authentication failures
  • Request and rate-limit errors
Members
  • GETList members
  • GETFetch one member
  • POSTChange a member's experience
  • POSTChange a member's quota points
  • PUTSet a member's rank
  • POSTPromote a member one rank
  • POSTDemote a member one rank
  • POSTAward a medal
  • DELETERemove a medal
  • POSTAward a qualification
  • DELETERemove a qualification
  • GETList a member's suspensions
  • POSTSuspend a member
  • POSTRestore a member's active suspension
  • POSTCancel a member's active suspension
Configuration
  • GETList ranks
  • GETFetch one rank
  • GETList medals
  • GETFetch one medal by name
  • GETList qualifications
  • GETFetch one qualification by name
Moderation
  • GETList blacklist entries
  • POSTCreate a blacklist entry
  • GETFetch one blacklist entry
  • PATCHUpdate a blacklist entry's description
  • DELETERemove a blacklist entry
  • GETList warnings
  • POSTIssue a warning
  • GETFetch one warning
  • PATCHUpdate a warning
  • DELETEDelete a warning
Events
  • GETList events
  • POSTCreate and announce an event
  • GETList curated event types
  • GETList approved event locations
  • GETFetch one event
  • POSTCancel an event
  • POSTFinish an event
  • POSTCreate a fresh Discord announcement
GuidesClan Labs websiteOpen dashboard Support
API v2
  • API overview
  • Authentication
  • API keys and scopes
  • Requests and responses
  • Errors and rate limits
  • Versioning and migration
  • Swagger migration
Troubleshooting
  • Authentication failures
  • Request and rate-limit errors
Members
  • GETList members
  • GETFetch one member
  • POSTChange a member's experience
  • POSTChange a member's quota points
  • PUTSet a member's rank
  • POSTPromote a member one rank
  • POSTDemote a member one rank
  • POSTAward a medal
  • DELETERemove a medal
  • POSTAward a qualification
  • DELETERemove a qualification
  • GETList a member's suspensions
  • POSTSuspend a member
  • POSTRestore a member's active suspension
  • POSTCancel a member's active suspension
Configuration
  • GETList ranks
  • GETFetch one rank
  • GETList medals
  • GETFetch one medal by name
  • GETList qualifications
  • GETFetch one qualification by name
Moderation
  • GETList blacklist entries
  • POSTCreate a blacklist entry
  • GETFetch one blacklist entry
  • PATCHUpdate a blacklist entry's description
  • DELETERemove a blacklist entry
  • GETList warnings
  • POSTIssue a warning
  • GETFetch one warning
  • PATCHUpdate a warning
  • DELETEDelete a warning
Events
  • GETList events
  • POSTCreate and announce an event
  • GETList curated event types
  • GETList approved event locations
  • GETFetch one event
  • POSTCancel an event
  • POSTFinish an event
  • POSTCreate a fresh Discord announcement
  1. API reference
  2. /
  3. Members
API v2 · MembersPro

Promote a member one rank

POST/v2/members/{userId}/rank/promote
Last updated 3 September 2026

Overview

Moves the member to the next rank by rank number.

Permission scope
members.ranks.write
Community feature
rank-management
Content type
application/json
ProAPI Rank Management

Change Roblox member ranks from your integration. Assigning the members.ranks.write scope requires Clan Labs Pro.

Compare plans

Authentication

Two headers are required

Send a current cl_live_… key as a Bearer token and the community’s Clan ID separately.

Authorization: Bearer YOUR_API_KEY
X-Clan-Id: COMMUNITY_ID

The key must be enabled, the community API master switch must be on, and the key must include members.ranks.write.

Parameters

NameLocationTypeRequiredConstraints and description
byqueryuserId | usernameNoHow 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.
userIdpathstringYesRoblox user id, or a username when `?by=username` is set.

Error responses

StatusWhen it is returned
400The request was malformed or failed validation.
401The API key is missing, malformed, or not recognised for this community.
403The key is disabled, lacks the required permission, or the community's subscription or tier does not cover API access or this feature.
404The requested resource does not exist.
409The request conflicts with current state.
429Rate limited.
500Unexpected server error.
Handle error codes, not prose
Error bodies use error.code as the stable machine-readable value. The message is for people and may become clearer over time.

Rate limits

This endpoint shares the API key’s configured request budget. A 429 response includes a Retry-After header and limit, remaining, and resetMs values in error.details. Wait for the indicated interval before retrying.

Related endpoints

GETList members/v2/membersGETFetch one member/v2/members/{userId}POSTChange a member's experience/v2/members/{userId}/experiencePOSTChange a member's quota points/v2/members/{userId}/quota-points

Examples use placeholders. Never put an API key in source control, a Roblox place file, screenshots, or support messages.

PreviousSet a member's rankNext Demote a member one rank
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://v3.api.clanlabs.co/v2/members/USER_ID/rank/promote?by=userId' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-Clan-Id: COMMUNITY_ID'

Response

200

The updated member

{
  "data": {
    "userId": 1234567,
    "username": "Builderman",
    "experience": 250,
    "quotaPoints": 3,
    "medals": [
      "Long Service"
    ],
    "qualifications": [
      "Marksman"
    ],
    "currentRank": {
      "uniqueId": 900001,
      "id": 10,
      "name": "Private",
      "experience": 200,
      "locked": false
    },
    "nextRank": {
      "uniqueId": 900001,
      "id": 10,
      "name": "Private",
      "experience": 200,
      "locked": false
    },
    "perks": {
      "boosting": true,
      "primary": true
    },
    "createdAt": 1735689600000,
    "lastUpdatedAt": 1735689600000
  }
}