REST API

The same player endpoints a page with browser access reads, called from your backend. A token with this scope is a known caller: it leaves the per-network budgets and gets the rate limit agreed for your organization. The scope appears in the console once the Laby team opened the API for your organization.

GET /api/v3/user/{uuid}/textures
Authorization: Bearer laby_org_...

All tokens of an organization share one rate limit window for this scope, so a second token does not double it. The scope only reads, and it stops working the moment API access is taken back, without touching a single token.

Report a purchase once it is paid. The player receives 3 percent of the price as LabyCoins (1000 coins per currency unit) and a notification; the coins are claimed on the rewards page. reference is your own order id and doubles as idempotency key, reporting the same reference twice returns 409.

POST /api/v3/cashback
Authorization: Bearer laby_org_...
Content-Type: application/json

{
  "uuid": "<player-uuid>",
  "price": 4.99,
  "reference": "order-2026-000123",
  "item_name": "VIP Rank"
}

→ 200 { "reference": 39482, "amount": 150 }

price is the amount the player paid, as a number. item_name is optional and shown to the player. amount in the response is the coin value credited; it is 0 for very small prices, then no notification is sent.

GET /api/v3/cashback/39482
GET /api/v3/cashback?reference=order-2026-000123

→ 200 {
  "reference": 39482,
  "added_at": "2026-09-06T10:15:00Z",
  "article_name": "VIP Rank",
  "amount": 150,
  "redeemed": false,
  "redeemed_at": null,
  "partner_reference": "order-2026-000123"
}

GET /cashback?user={uuid} lists every cashback you reported for one player, newest first, and returns 404 when there is none.

The paths of the retired next.labymod.net API (POST /cashback/create, GET /cashback/get/{id}, GET /cashback/get/{reference}?server_reference=true, GET /cashback/get/user/{uuid}) still work on laby.net with the same payloads, but are deprecated: switch to the routes above when you rotate your token.

Achievements are defined and reviewed on laby.net; the API only hands them out. Every call addresses an achievement by the key you gave it and a server by its name, the one in the URL of its page on laby.net, so a plugin needs no internal ids. Granting is idempotent: replaying a queue never fails, it reports the repeat as a no-op.

POST /api/v3/achievements/servers/labymod/grant
Authorization: Bearer laby_org_...
Content-Type: application/json

{
  "achievement": "first_win",
  "uuid": "<player-uuid>"
}

→ 200 { "granted": true, "reactivated": false }

granted is false when the player already holds it, so you can call this on every login without checking first. reactivated is true when a previously revoked grant came back. The player is notified only on a real grant, and only while the achievement is approved.

POST /api/v3/achievements/servers/labymod/grant/bulk
Authorization: Bearer laby_org_...
Content-Type: application/json

{
  "achievement": "first_win",
  "uuids": ["<uuid-a>", "<uuid-b>"]
}

→ 200 {
  "results": [
    { "uuid": "<uuid-a>", "result": "granted" },
    { "uuid": "<uuid-b>", "result": "unknown_user" }
  ],
  "granted": 1,
  "total": 2
}

At most 100 players per request. A player without a Laby.net account does not fail the batch, they come back as unknown_user; a repeat is already_granted. Send the rest of your roster in further requests.

DELETE /api/v3/achievements/servers/labymod/grant
Authorization: Bearer laby_org_...
Content-Type: application/json

{
  "achievement": "first_win",
  "uuid": "<player-uuid>"
}

→ 200 { "success": true }

GET /api/v3/achievements/servers
→ 200 { "servers": [ { "id": 12, "name": "labymod", "nice_name": "LabyMod" } ] }

GET /api/v3/achievements/servers/labymod
→ 200 {
  "server": { "id": 12, "name": "labymod", "nice_name": "LabyMod" },
  "achievements": [
    { "key": "first_win", "name": "First win", "status": "ACTIVE",
      "grantable": true, "use_count": 1428 }
  ]
}

GET /api/v3/achievements/servers/labymod/first_win/grants?page=1&pageSize=100
→ 200 {
  "grants": [ { "uuid": "...", "username": "...",
                "granted_at": "2026-09-06T10:15:00Z", "source": "API" } ],
  "total": 1428, "page": 1, "page_size": 100
}

status is PENDING while a new achievement waits for review, ACTIVE once it is approved, and REJECTED, DISABLED or BLOCKED otherwise. Only grantable ones accept new grants, anything else answers 409, so check the list after changing your configuration. Grants survive a rejection, they are just hidden until the achievement is live again.

Every route allows 120 requests per minute and token. A server your organization has not claimed answers 403, an unknown key 404.