API v2 · Members

Change a member's experience

POST/v2/members/{userId}/experience

Last updated 1 October 2026

Overview

Writes an audit entry and re-runs AutoRank. increment/decrement are clamped to Experience.AwardLimits.API; set deliberately is not. A scheduled AutoRank outcome may return 504 with operation status headers after the experience change is saved. Check the operation before repeating the experience change.

Permission scope: members.experience.write
Community feature: experience
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

Request body

A JSON request body is required.

Field	Type	Required	Constraints and description
`op`	`increment \| decrement \| set`	Yes	`increment` and `decrement` are clamped to the community's per-call API award limit; `set` is not.
`amount`	`integer`	Yes	min 0, max 9007199254740991
`reason`	`string`	No	min length 1, max length 256

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/experience?by=userId' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-Clan-Id: COMMUNITY_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "op": "increment",
  "amount": 10
}'

Response

200

The member

{
  "data": {
    "userId": 1234567,
    "username": "PixelComet482",
    "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
  }
}

Change a member's experience | 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