cormacAPI
API key

Members

Change a member's XP

PATCH/v1/guilds/:guildId/members/:userId/progression
NeedsOwner's keycormac+progression plugin onprogression:write

Set a member's XP or level, or add to it or take from it. Their reward roles move to match, the same as with /xp in Discord, and no level-up message is posted.

addXp is the one write where a retry changes the outcome, so send an Idempotency-Key with it if you retry on timeouts. Changes to one member run one at a time inside cormac, together with XP earned from messages, so a burst of calls never loses one.

previous has no rank: working it out again would mean ranking every member twice.

Every change shows in the server's Recent changes on the dashboard, with the key's name and prefix and the reason if you send one. Writes are server-side only: browsers are refused at the CORS preflight, so a key that can change data never has to sit in a web page.

Request body

xpinteger
Set total XP to exactly this. Up to the XP level 1,000 starts at.
levelinteger · 0 to 1,000
Set the level, at the XP that level starts at.
addXpinteger · -1,000,000 to 1,000,000
Add this much, or take it away when negative. Not 0. Total XP never drops below 0.

Send exactly one of these. As JSON, with Content-Type: application/json.

Headers

Idempotency-Keystring
Any string up to 255 characters you choose for this change, such as a UUID. A retry with the same key gets the first response back instead of making the change again, for 24 hours. Reusing a key for a different request is a 400; retrying while the first is still running is a 409 IDEMPOTENCY_CONFLICT. A 5xx is not kept, so the same key can be retried.
X-Audit-Log-Reasonstring
Why, in up to 200 characters, URI-encoded as Discord expects. It shows next to the change in the server's Recent changes.

Errors

400 BAD_REQUEST when:

  • The body is not JSON, or has anything other than exactly one of xp, level or addXp.
  • The value is not a whole number, is negative where it can't be, or is past its limit.

Plus the failures every endpoint shares, listed under errors & limits.