{ "openapi": "3.1.0", "info": { "title": "CEEJAY API", "version": "1.2.0", "summary": "Work with a Discord community on CEEJAY from your own game, app or platform.", "description": "The CEEJAY API lets your own game, app or platform work with a Discord community on CEEJAY. Give XP, move currency, complete quests, link accounts, manage roles and post messages from your server, and receive a signed webhook the moment something happens in the community.\n\n## Base URL\n\nEvery request goes to your dashboard's URL followed by `/api/v1`.\n\n- Shared CEEJAY service: `https://ceejay.communitystudios.xyz/api/v1`\n- Dedicated instance: the URL you see in your browser when you open your dashboard, followed by `/api/v1`.\n\nOne operation is the exception. The older endpoint of Complete a quest task is at the dashboard's URL followed by `/api/quests/external/complete`, with no `/v1`, and it lists its own servers. It still works; new code uses `POST /quests/tasks/complete`.\n\n## Authentication\n\nSend an API key as a bearer token: `Authorization: Bearer ceejay_sk_…`. Create keys in the dashboard under **Settings → Developers → API Keys**. A key belongs to one Discord server, so you never send a server ID: every request is for the key's server. Each operation names the scope it needs. Community details (`GET /community`) needs none, and returns what the key may do and what this instance supports: make it your first call.\n\n## Conventions\n\n- Send `Content-Type: application/json` with every request that has a body. With that header, a body that is not valid JSON is refused before the key is checked, with status `400` and the plain-text body `Invalid JSON`. A body over 1 MB gets `413`. These two responses, and the response for a path that does not exist, are returned before CEEJAY's own code runs: they are not JSON and carry no `code`. Without the header the body is not read as JSON: it reaches the operation as text and is refused with `400`. A body that is JSON but not an object (`null`, a string, a number or a list) is refused the same way. The message is `The request body must be a JSON object`, except on Complete a shop delivery and Complete a quest task, which return `400` with their own first message. A form content type, which `curl -d` sends when you set none, is read as a form: the JSON fields are not found, and the first field check fails.\n- Each field has one current name, in camelCase, in requests and responses. The member is `discordId`, a game's own ID for the member is `playerId` and its name `playerName`, a note is `reason`. Every name a request or a response had before is still accepted and still returned, for as long as version 1 exists. A request property that has an older name lists it under `x-also-accepted`; when both names are sent, the older one is used. A response field that has a newer twin is marked `deprecated`, and is still returned.\n- Discord IDs are strings of 17 to 20 digits. Always send and read them as strings. A JSON number cannot represent all the digits, so its last ones would change and it could name a different ID. A Discord ID that is not a string is refused with `400`, like one that is not 17 to 20 digits. Complete a quest task is the exception: a `discordId` of the wrong kind returns `202` there. CEEJAY's own IDs of quests, programs and purchases are numbers in every response, and a request takes them as a number or as a string of digits.\n- Text is sent as a JSON string. A text field that contains a number, a list or an object is refused with `400`, and so is text that contains a null character (U+0000) where CEEJAY stores it. Complete a quest task is the exception for `xHandle`, `wallet`, `github` and `twitch`: a whole number is read as its digits, and any other value that is not a string returns `202`.\n- A successful response is `{ \"success\": true, \"data\": … }`. A list adds `\"page\": { \"nextCursor\", \"limit\" }` beside `data`: send `nextCursor` back as `cursor` for the next page, and stop when it is `null`. Three operations keep the fields they had beside `success` before, and carry `data` as well: List quests (`total`, `limit`, `offset`), Complete a quest task (`matched`, `completed`) and Complete a shop delivery (`purchaseId`, `status`, `alreadyDone`, `refunded`).\n- A failed response has a non-2xx status and `{ \"error\": \"message\", \"code\": \"fixed_code\", \"requestId\": \"req_…\" }`. Some codes add fields, described on the operations that return them. Act on `code`: the list of codes is closed for version 1 (the `ErrorCode` schema), while the `error` message text can change. Do not act on the status alone either: four refusals keep the status `400` they have always had (`quest_not_active`, `quest_already_completed`, `quest_limit_reached`, `insufficient_balance`) where newer rule refusals return `409`.\n- Every response includes `X-Request-Id`, the same value as `requestId` in an error body. Quote it when you ask us about a request.\n- Dates are ISO 8601 strings in UTC.\n- Call the API from your own server. Never call it from a browser, a mobile app or a game client: a key in client code can be copied, and browsers on other websites are not allowed to call the API.\n- Within version 1 nothing is renamed or removed. Every operation carries `x-since`, the version it first appeared in.\n\n## Connect\n\nConnect links a player of your game to their Discord account in the community. The operations under the **Connect** tag are the ones your own server makes with a secret key that has the `players:connect` scope. The requests a game makes itself, with the public key it ships with, are in a second file, `openapi-connect.json`, served beside this one: they take another kind of key and have no scopes. Once a player is connected, the operations under the **Players** and **Field map** tags read the player, send data about them (fields and events), disconnect them and delete the data CEEJAY stores for them. Connect is switched on per instance: where it is off, these operations return `404` with the code `not_available` and `feature: \"players\"`. A game can also show the community's quests, shop, rank and daily reward, and sell from its shop, with a player session: those requests are in the second file too, and an item a player buys in a game is delivered to your server with a `player` that identifies them (see the **Shop delivery webhooks** tag).\n\n## Rate limits\n\nEach key allows 60 requests per minute unless a higher limit was set on it, and never more than 600. Requests are counted per key in one-minute windows. Every response to a request made with a known key includes the key's rate limit status: `X-RateLimit-Limit` (the key's requests per minute), `X-RateLimit-Remaining` (requests left in the window) and `X-RateLimit-Reset` (whole seconds until the window ends). Over the limit, the API returns `429` with the code `rate_limited`, a `Retry-After` header (in seconds) and `retryAfter` in the body. Every request made with a valid key is counted, whatever the response, including one refused for a missing scope (`403`). The limit is checked before the scope. A request refused for a bad key (`401`) is not counted and carries no rate limit headers.\n\nThe five Connect operations of a studio's server have a limit of their own and are not counted against the key's number: 600 requests a minute for each game. One key also has an abuse limit of 6,000 a minute across them. The player operations (the **Players** and **Field map** tags) use the key's own number: a call that carries up to 500 players or events is one request. Their three headers report the game's 600 once the request has found its game, and the key's 6,000 on a response returned before that.\n\nDiscord limits CEEJAY's bot as well. When that limit is reached, an operation that calls Discord returns `429` with the code `discord_rate_limited`, and `retryAfter` when Discord provided a retry time. That response does not mean the key's own window is used up.\n\n## Retrying safely\n\nEvery operation that creates or changes data accepts an optional `idempotencyKey` in the JSON body (an `Idempotency-Key` header is not read). When the same request is sent again with its key, nothing happens a second time: the response is the original one, with `duplicate: true` and the header `Idempotent-Replayed: true`. One key is one request, across every operation: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. The same key on another operation, or with other values, returns `409` with the code `idempotency_key_reused`. A key belongs to the API key that sent it. A key is stored only when its request was applied, so a refused request can be retried with the same key, and keys are retained for 30 days.\n\nTwo more responses are about a request whose first attempt may still be running. `409` with the code `idempotency_in_progress` means wait the `retryAfter` seconds and retry. `409` with the code `idempotency_outcome_unknown` comes from Send a message, Emit an event and Complete a quest task when a first attempt never finished: CEEJAY cannot know whether it took effect, and does not repeat it. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing.\n\nGrant currency, Deduct currency and Complete a quest took a key before version 1.0.0 under the name `idempotency_key`. That name is still accepted on those three, their keys keep working on an instance that is still being updated, and a currency movement made with a key is recognised from the member's transaction history permanently. The other operations read `idempotencyKey` only.\n\n## Webhooks\n\nCEEJAY sends signed HTTP POST requests to the URLs you add under **Settings → Developers → Webhooks**. The `webhooks` section of this document lists every event and its payload.\n\n- Every delivery has the same envelope: `{ \"event\", \"data\", \"serverId\", \"timestamp\", \"id\" }`, and the headers `Content-Type: application/json`, `X-CEEJAY-Event` (the event name) and the signature headers.\n- Each subscription has its own signing secret. The dashboard shows it once, right after you press **Create**: copy it then. If you lose it, delete the subscription and add it again.\n- Every delivery carries signature version 2 in four headers: `X-CEEJAY-Delivery` (the delivery ID), `X-CEEJAY-Attempt` (`1` for the first attempt, then `2`, `3` and so on), `X-CEEJAY-Timestamp` (the Unix time in seconds at which this attempt was signed) and `X-CEEJAY-Signature-V2`. The signature is the HMAC-SHA256, as 64 lower-case hexadecimal characters, of the text `v2....`, keyed with the signing secret used as text. Compute it over the exact bytes you received, before parsing them, compare in constant time, and refuse a delivery whose time is more than 300 seconds from your own clock. Inside those 300 seconds a captured delivery can be replayed, so keep each `X-CEEJAY-Delivery` with its `X-CEEJAY-Attempt` for five minutes and ignore one you have already handled.\n- The legacy signature is still sent beside it, unchanged: `X-CEEJAY-Signature` is `sha256=` followed by the HMAC-SHA256 of the raw request body, as lowercase hex, keyed with the signing secret of the subscription. It includes no time.\n- Respond with any 2xx status within 5 seconds. Any other status, a redirect (redirects are not followed) or no response is a failed delivery. The URL must be a public https URL.\n- A failed delivery is retried up to 4 more times, with the same `id` and `X-CEEJAY-Delivery`, the next `X-CEEJAY-Attempt` and a new `X-CEEJAY-Timestamp`: about 30 seconds, 2 minutes, 4½ minutes and 8 minutes after the first try. CEEJAY's retry worker runs once a minute, so each retry can be delivered up to a minute late.\n- After 10 failed deliveries in a row, a subscription is switched off. A successful delivery resets the count, and so does switching the subscription back on.\n- \"Delivered by your API\" shop items are different: they send one request to the URL set on the item, with the item's own secret. See the **Shop delivery webhooks** tag.", "contact": { "name": "CEEJAY support", "url": "https://communitystudios.xyz/contact" } }, "servers": [ { "url": "https://ceejay.communitystudios.xyz/api/v1", "description": "The shared CEEJAY service." }, { "url": "https://{dashboardHost}/api/v1", "description": "A dedicated CEEJAY instance: your dashboard's address followed by /api/v1.", "variables": { "dashboardHost": { "default": "dashboard.example.com", "description": "The domain you see in your browser when you open your dashboard, without https://." } } } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Community", "description": "Find out which community a key belongs to, what the key may do and what this instance supports." }, { "name": "Members", "description": "Read a member and link their accounts in your game or on other platforms." }, { "name": "Connect", "description": "Link a player of your game to their Discord account, from your own server: verify a player with a pass, start a connect session, read it and confirm it on the game's behalf. These need the scope `players:connect`, which a `*` key does not include. The requests a game makes itself are in `openapi-connect.json`. What happens after a player is connected (their data, events, and disconnecting or deleting them) is under the **Players** and **Field map** tags." }, { "name": "Players", "description": "The players of a game who are connected to a Discord member: read them, send data about them (fields and events), disconnect one and delete the data CEEJAY stores for one. These need `players:read`, `players:write`, `players:connect` or `players:delete`. A `*` key includes the first two and not the last two. They are counted against the key's own requests per minute." }, { "name": "Field map", "description": "The map between the names a game uses for its data and the fields of the community's members. A key reads the map and proposes to it with `players:read` and `players:write`. The community's team approves what is proposed." }, { "name": "XP", "description": "Read, grant and deduct XP, for the whole server or inside a community program." }, { "name": "Programs", "description": "List community programs." }, { "name": "Economy", "description": "Read, grant and deduct a member's currency." }, { "name": "Quests", "description": "List quests, complete one for a member, or report that a member finished a quest task." }, { "name": "Roles", "description": "List Discord roles, and grant and revoke them." }, { "name": "Channels", "description": "List the channels of your server." }, { "name": "Messages", "description": "Post messages and embeds to channels in your server." }, { "name": "Events", "description": "Send your own events to your webhook subscribers." }, { "name": "Shop", "description": "List the deliveries of \"Delivered by your API\" shop items awaiting fulfilment by your server, and complete them." }, { "name": "Webhook events", "description": "Events CEEJAY sends to the webhook subscriptions you add under **Settings → Developers → Webhooks**. A subscription lists the events it wants, or `*` for all of them.\n\nEach delivery is an HTTP POST with a JSON body of `{ \"event\", \"data\", \"serverId\", \"timestamp\", \"id\" }` and the headers `Content-Type: application/json` and `X-CEEJAY-Event`. Every delivery carries signature version 2 in four headers: `X-CEEJAY-Delivery` (the delivery ID), `X-CEEJAY-Attempt` (`1` for the first attempt, then `2`, `3` and so on), `X-CEEJAY-Timestamp` (the Unix time in seconds at which this attempt was signed) and `X-CEEJAY-Signature-V2`. The signature is the HMAC-SHA256, as 64 lower-case hexadecimal characters, of the text `v2....`, keyed with the signing secret used as text. Compute it over the exact bytes you received, before parsing them, compare in constant time, and refuse a delivery whose time is more than 300 seconds from your own clock. Inside those 300 seconds a captured delivery can be replayed, so keep each `X-CEEJAY-Delivery` with its `X-CEEJAY-Attempt` for five minutes and ignore one you have already handled. The signing secret is the subscription's, which the dashboard shows once, right after you create the subscription. The delivery ID is the body's `id`, and a retry carries the same ID with the next attempt number and a new time.\n\nThe legacy signature is still sent beside it, unchanged, for as long as version 1 exists: `X-CEEJAY-Signature` is `sha256=` followed by the HMAC-SHA256 of the raw body, as lowercase hex, keyed with the same secret. It includes no time.\n\nAn event whose `data` has `userId` carries the same value as `data.discordId`, the name the rest of the API uses. Respond with any 2xx status within 5 seconds. Failed deliveries are retried up to 4 more times. After 10 failed deliveries in a row a subscription is switched off. Switching it back on starts the count again from zero." }, { "name": "Shop delivery webhooks", "description": "When a member buys a \"Delivered by your API\" item, or earns a reward that is set to be delivered by your API, CEEJAY sends one signed POST to the endpoint URL set on the item. Your response decides what happens to the purchase. These requests are separate from webhook subscriptions. An item a player buys in a game (through the game's Buy a shop item) is delivered the same way, and its body also carries `player`: `{ \"game\", \"player_id\", \"proof\" }`, in snake_case like the rest of the body. It names the player the item was bought for, as it was at the purchase, so your server can deliver the item to the right player; it is left out for a purchase made in Discord.\n\nHeaders: `Content-Type: application/json`, `Accept: application/json`, `User-Agent: CEEJAY-Shop/1`, and the signature headers. Every delivery carries signature version 2 in four headers: `X-CEEJAY-Delivery` (the delivery ID), `X-CEEJAY-Attempt` (`1` for the first attempt, then `2`, `3` and so on), `X-CEEJAY-Timestamp` (the Unix time in seconds at which this attempt was signed) and `X-CEEJAY-Signature-V2`. The signature is the HMAC-SHA256, as 64 lower-case hexadecimal characters, of the text `v2....`, keyed with the signing secret used as text. Compute it over the exact bytes you received, before parsing them, compare in constant time, and refuse a delivery whose time is more than 300 seconds from your own clock. Inside those 300 seconds a captured delivery can be replayed, so keep each `X-CEEJAY-Delivery` with its `X-CEEJAY-Attempt` for five minutes and ignore one you have already handled. The signing secret is the item's. The delivery ID is `shop_`, the same on every retry: de-duplicate on it.\n\nThe legacy signature is still sent beside it, unchanged, for as long as version 1 exists: `X-CEEJAY-Signature: t=,v1=`, where `v1` is the HMAC-SHA256, as lowercase hex, of the text `.`, keyed with the item's signing secret, and `t` is the same time as `X-CEEJAY-Timestamp`.\n\nYour response (CEEJAY allows 5 seconds and reads up to 64 KB): a 2xx with an empty body, or `{ \"status\": \"delivered\" }`, marks the purchase delivered. Status `202`, or a 2xx with `{ \"status\": \"pending\" }`, means the delivery is pending: call `POST /shop/purchases/{purchaseId}/complete` once it is complete. A 2xx with `{ \"status\": \"failed\", \"message\": \"…\" }`, a redirect or a 4xx other than `408` and `429` refuses the delivery and refunds the member. `408`, `429`, a 5xx, a timeout or a connection error is retried about every hour with the same `delivery_id`, and the member is refunded after 3 failed attempts in total. You can respond pending to a retry as well: the retries stop, the attempt is not counted as failed, and the purchase awaits your callback. A purchase still awaiting your callback after 24 hours is refunded. `GET /shop/purchases` lists the purchases awaiting your confirmation." } ], "paths": { "/community": { "get": { "tags": [ "Community" ], "summary": "Community details", "description": "Says which community a key belongs to, what the key may do, and which operations this instance can serve. Make it your first call.\n\n**Required scope:** none. Any valid key can call it.\n\n`key` holds the name, the scopes, the rate limit and the expiry of the key that made the call. `features` says, per group of operations, whether this instance can serve them: a request for a feature that reads `available: false` returns `404` with the code `not_available`. `platforms` lists the names Link an account takes.\n\nIt changes nothing. It never returns the key or its hash, the community's other keys, or the name or value of any setting.", "operationId": "getCommunity", "x-required-scope": [], "x-since": "1.0.0", "responses": { "200": { "description": "The community.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityResponse" }, "examples": { "community": { "summary": "A community", "value": { "success": true, "data": { "serverId": "721104938271003842", "name": "Harbour Town", "apiVersion": "1.1.0", "key": { "name": "Game server", "scopes": [ "xp:grant", "quests:complete" ], "rateLimitPerMinute": 60, "expiresAt": null }, "features": { "xp": { "available": true }, "economy": { "available": true, "enabled": true }, "quests": { "available": true, "dailyQuestLimit": 5 }, "programs": { "available": true }, "linking": { "available": true }, "roles": { "available": true }, "messages": { "available": true }, "events": { "available": true }, "shopDelivery": { "available": true }, "retryKeys": { "available": true }, "players": { "available": true }, "gameLoop": { "available": true } }, "platforms": { "builtIn": [ "github", "twitch", "steam", "twitter", "xbox", "playstation", "metamask", "epic", "youtube", "riot", "battlenet", "roblox", "reddit", "kick", "patreon", "tiktok", "bluesky", "lastfm", "spotify" ], "custom": [ { "slug": "rugby_manager", "name": "Rugby Manager" } ] } } } } } } } }, "400": { "$ref": "#/components/responses/CommunityRequired" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CommunityNotCovered" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/{discordId}": { "get": { "tags": [ "Members" ], "summary": "Get a member", "description": "Returns one member's profile, XP and level, currency and linked platform accounts in a single call.\n\n**Required scope:** `members:read` (a key with the `*` scope can also call it).\n\n`404` always means CEEJAY has no profile for that Discord ID on your server; Discord is not asked. A member who exists but has no currency returns `200` with a zeroed `economy` object. `level` is worked out from `xp` on your server's XP curve each time. Each linked account includes the game's own ID and name as `playerId` and `playerName`. A game account the member connected themselves through Connect is in `connections` only for a key that has the `players:read` scope (a `*` key does). An account your own server linked with Link an account is always there. A key limited to some games (a secret key with games listed in the dashboard) sees only the connections to those games. Each entry carries `proof`: for a connection to a game it says whether the player was verified (`verified`) or only supplied by the game (`basic`), and it is `null` for every other account. Do not grant a member anything for a player ID whose `proof` is `basic`.", "operationId": "getMember", "x-required-scope": [ "members:read" ], "x-since": "1.0.0", "parameters": [ { "$ref": "#/components/parameters/DiscordIdPath" } ], "responses": { "200": { "description": "The member.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponse" }, "examples": { "member": { "summary": "A member with a linked account", "value": { "success": true, "data": { "discordId": "409876543210987654", "displayName": "nova", "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f6.png", "xp": 8450, "level": 12, "totalMessages": 3411, "totalVoiceMinutes": 862, "joinedAt": "2025-11-04T18:22:07.000Z", "lastUpdated": "2026-10-01T09:14:22.118Z", "economy": { "balance": 2450, "totalEarned": 9100, "totalSpent": 6650 }, "connections": [ { "platform": "twitch", "platformUserId": "123456789", "platformUsername": "novaplays", "playerId": "123456789", "playerName": "novaplays", "connectedAt": "2026-03-12T16:40:11.000Z", "proof": null } ] } } } } } } }, "400": { "description": "The Discord ID in the path is not 17 to 20 digits.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "CEEJAY has no profile for this member on your server.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknown": { "summary": "Unknown member", "value": { "error": "Member not found", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/link": { "post": { "tags": [ "Members" ], "summary": "Link an account", "description": "Links a member's account in your game or on another platform (Twitch, Steam, Roblox and others) to their Discord ID, so activity on your platform can be tied to the community member.\n\n**Required scope:** `members:link` (a key with the `*` scope can also call it).\n\n**The platform** must be one that is known. That is one of the platforms CEEJAY knows by name (`github`, `twitch`, `steam`, `twitter`, `xbox`, `playstation`, `metamask`, `epic`, `youtube`, `riot`, `battlenet`, `roblox`, `reddit`, `kick`, `patreon`, `tiktok`, `bluesky`, `lastfm`, `spotify`), a custom platform your community added under **Settings → Developers → Platforms** (it is saved there in **API Link** mode, and the value to send is its **Slug**, the name it is stored under), or a platform your community already has at least one link for. Any other name returns `400` with the code `unknown_platform`. An X account is linked as `twitter` and a wallet as `metamask`. Community details (`GET /community`) lists the platforms your key can use.\n\n**The member** must be in your server. An ID CEEJAY has no member profile for is looked up in Discord first: an ID that is not in your server returns `404` with the code `member_not_found`, and when the Discord API is unavailable the call returns `503` with the code `discord_unavailable`. Nothing is linked in either case. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.\n\n**The ID** is `playerId`, the game's own ID for the member. Spaces at either end are removed before it is stored.\n\nSafe to repeat: linking the same platform again for the same member updates the link (the ID, and the name when you send one) and makes it active again if it had been disconnected.\n\nTwo links are rejected with `409`, and nothing is changed. A member who linked the platform themselves, by signing in to it, keeps that account while the link is active: a call that names a different `playerId` returns the code `linked_by_sign_in`. Capitals and spaces at the ends do not make an ID different. Once the member has disconnected the account, the platform can be linked again through the API. That link is a new one made by your key, also when it names the same account: it does not bring the member's sign-in back. And an account belongs to one member of your server at a time: a `playerId` that another member has an active link for on the same platform returns the code `player_already_linked`. Concurrent calls that send one account for two members are processed one at a time: the first links it, and the second gets `player_already_linked`. A member who already has an active link for that account can always send it again, and their link is updated as before. An account moves from one member to another only after the first member's link is disconnected, and no operation of this API disconnects a link.\n\nWhen you send the account a member signed in with, in other capitals or with spaces, the link keeps the capitalisation the member signed in with, and `playerId` in the response is the stored value. A link the API points at a different account no longer carries the old account's sign-in, and neither does a link the API makes again after the member disconnected it.\n\n**A platform that is a game.** On an instance that offers Connect, a game set up for your community is a platform from the day it is created: send its slug as `platform`. A link under it is a game connection at the verified level, on your server's word, and the member is shown no page for it. For a game, `playerId` must be one a game can use (1 to 128 letters, digits and `. _ : @ | + = -`, starting with a letter or a digit), or the call returns `400` with the code `bad_player_id`. A game that is paused returns `409` with `game_paused`, a key limited to other games `403` with `game_not_allowed`, a game made for children `403` with `audience_not_allowed`, and a game that was removed `404` with `game_not_found`. A member who ended their connection to the game themselves cannot be linked to it again by a key (`409` with `member_disconnected`), and neither can a member whose connection to it ended because the player is under age (`403` with `under_age`): in both cases only the member connecting again through Connect clears it. A player the community blocked cannot be linked at all (`409` with `player_blocked`). A connection the member made themselves through Connect is protected like a sign-in: a call that names a different `playerId` returns `linked_by_sign_in`. Every other platform name is handled as before.\n\nLinking also does these things in the background. They never make the call fail. It adds a `connect_` entry to the member's activity history, which sends the `account.linked` webhook the first time the member links that platform. It fulfils rewards that were waiting for that platform. It grants the community's own reward for linking an account, if one is set up, once per member and platform. For a platform that is a game the community's own reward for linking an account is not granted. CEEJAY's bot works the connection instead, shortly after the response, as it does any connection to the game: it sends `player.connected`, and where the connection meets the proof the game asks for, it also adds the `account.linked` entry (once for each member and game), releases rewards that waited for a linked account of this game, and pays the game's own reward for connecting, if one is set up.\n\n`data` includes the link under the names the rest of the API uses, and alongside them the snake_case fields this response has always returned.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member, platform, ID and name. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is linked. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing.", "operationId": "linkMemberAccount", "x-required-scope": [ "members:link" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAccountRequest" }, "examples": { "roblox": { "summary": "Link a Roblox account", "value": { "discordId": "409876543210987654", "platform": "roblox", "playerId": "88213004", "playerName": "novaplays" } } } } } }, "responses": { "200": { "description": "The link. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAccountResponse" }, "examples": { "linked": { "summary": "Linked", "value": { "success": true, "data": { "id": 311, "server_id": "721104938271003842", "user_id": "409876543210987654", "platform": "roblox", "platform_user_id": "88213004", "platform_username": "novaplays", "is_active": true, "connected_at": "2026-10-01T09:14:22.118Z", "connectionId": "311", "discordId": "409876543210987654", "playerId": "88213004", "playerName": "novaplays", "active": true, "connectedAt": "2026-10-01T09:14:22.118Z", "duplicate": false } } } } } } }, "400": { "description": "The request was rejected and nothing was linked. The checks run in this order: the body, Discord ID, platform, the ID, the type of the name, the three lengths, a null character in any of the three, the characters of the platform, the idempotency key, then whether the platform is known. A message names the spelling you sent (`playerId` or `platformUserId`, `playerName` or `platformUsername`); a missing ID is called `playerId`. When the platform is a game, the alphabet of `playerId` is checked after the platform is known (`bad_player_id`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "noPlatform": { "summary": "No platform, or not text", "value": { "error": "platform is required", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "noPlayerId": { "summary": "No ID, not text, or empty once trimmed", "value": { "error": "playerId is required", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "noPlatformUserId": { "summary": "The same, when the deprecated alias was sent", "value": { "error": "platformUserId is required", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platformUserId" } }, "badName": { "summary": "Name not text", "value": { "error": "playerName must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerName" } }, "longPlatform": { "summary": "Platform over 50 characters", "value": { "error": "platform cannot exceed 50 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "longPlayerId": { "summary": "ID over 255 characters", "value": { "error": "playerId cannot exceed 255 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "longName": { "summary": "Name over 255 characters", "value": { "error": "playerName cannot exceed 255 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerName" } }, "nullInPlatform": { "summary": "A null character in the platform", "value": { "error": "platform cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "nullInPlayerId": { "summary": "A null character in the ID", "value": { "error": "playerId cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "nullInName": { "summary": "A null character in the name", "value": { "error": "playerName cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerName" } }, "badPlatform": { "summary": "A platform with other characters", "value": { "error": "platform can only contain letters, digits and underscores", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "unknownPlatform": { "summary": "A platform that is not known", "value": { "error": "Unknown platform. Add it as a custom platform under Settings, Developers, Platforms, then link again", "code": "unknown_platform", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badPlayerId": { "summary": "A game's player ID outside the alphabet", "value": { "error": "playerId must be 1 to 128 characters: letters, digits and . _ : @ | + = -, starting with a letter or a digit", "code": "bad_player_id", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not have `members:link` (`insufficient_scope`: the body lists what was needed and what the key has, and the request still counts toward the key's rate limit). Or the platform is a game that cannot be linked under: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), the game is made for children (`audience_not_allowed`), or this member's connection to the game ended because the player is under age (`under_age`: this request carries no age answer, so a key cannot link them to the game again; the member connecting again through Connect clears it).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without the scope", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "economy:grant" ], "granted": [ "xp:grant", "xp:read" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "underAge": { "summary": "The member's connection to the game ended for age", "value": { "error": "This player cannot be connected", "code": "under_age", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "The Discord ID is not a member of your server (`member_not_found`), or this instance does not support account linking yet (`not_available`). Nothing was linked. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying. Or the platform is the slug of a game that was removed (`game_not_found`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAMember": { "summary": "Not a member of your server", "value": { "error": "Member not found", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "linking" } }, "gameNotFound": { "summary": "A game that was removed", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The link was rejected and nothing was changed: the member linked this platform by signing in (`linked_by_sign_in`), or another member has this account (`player_already_linked`). The `idempotencyKey` was already used by this API key for a different request (`idempotency_key_reused`: another operation, or other values), or the first request with it is still being processed (`idempotency_in_progress`: wait `retryAfter` seconds and retry). Nothing was changed by this call. When the platform is a game: the game is paused (`game_paused`), the member ended their connection to it themselves (`member_disconnected`), or the community blocked the player (`player_blocked`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "linkedBySignIn": { "summary": "The member linked this platform by signing in", "value": { "error": "The member linked this platform by signing in, so only they can change it", "code": "linked_by_sign_in", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "playerAlreadyLinked": { "summary": "Another member has this account", "value": { "error": "This playerId is already linked to another member in this server", "code": "player_already_linked", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyReused": { "summary": "The key was already used for a different request", "value": { "error": "This idempotencyKey was already used for a different request", "code": "idempotency_key_reused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyInProgress": { "summary": "The first request with this key is still running", "value": { "error": "The first request with this idempotencyKey is still running. Try again in a few seconds.", "code": "idempotency_in_progress", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 5 } }, "gamePaused": { "summary": "The game is paused", "value": { "error": "This game is paused", "code": "game_paused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "memberDisconnected": { "summary": "The member disconnected the game themselves", "value": { "error": "The member disconnected this game themselves, so only they can connect it again", "code": "member_disconnected", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "playerBlocked": { "summary": "The community blocked the player", "value": { "error": "This player cannot be connected until the community lifts a block", "code": "player_blocked", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "A check CEEJAY needs could not be made, and nothing was changed. Either CEEJAY has no profile for this Discord ID and could not check with Discord whether it is a member of your server (`discord_unavailable`: retry the request shortly), or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "discordUnavailable": { "summary": "Discord could not be asked", "value": { "error": "Could not check with Discord that this ID is a member of the server, so nothing was changed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/xp/balance": { "get": { "tags": [ "XP" ], "summary": "Get XP balance", "description": "Returns a member's total XP and level, without the rest of their profile.\n\n**Required scope:** `xp:read` (a key with the `*` scope can also call it).\n\nA member CEEJAY has not seen is not an error: the call returns `200` with `xp` and `level` at `0` and `lastUpdated` as `null`, so you can call it without checking the member first. Reading creates nothing.", "operationId": "getXpBalance", "x-required-scope": [ "xp:read" ], "x-since": "1.0.0", "parameters": [ { "$ref": "#/components/parameters/DiscordIdQuery" } ], "responses": { "200": { "description": "The member's XP.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XpBalanceResponse" }, "examples": { "member": { "summary": "A member with XP", "value": { "success": true, "data": { "discordId": "409876543210987654", "xp": 8450, "level": 12, "lastUpdated": "2026-10-01T09:14:22.118Z" } } }, "unknown": { "summary": "A member CEEJAY has not seen", "value": { "success": true, "data": { "discordId": "409876543210987654", "xp": 0, "level": 0, "lastUpdated": null } } } } } } }, "400": { "description": "The Discord ID is missing, not 17 to 20 digits, or was sent more than once.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/xp/grant": { "post": { "tags": [ "XP" ], "summary": "Grant XP", "description": "Grants a member XP and tells you whether it took them up a level.\n\n**Required scope:** `xp:grant` (a key with the `*` scope can also call it).\n\nA member of your server CEEJAY has no profile for yet gets one, so you can reward someone who plays your game before they have said anything in Discord. CEEJAY first checks with Discord whether such an ID is a member of your server: an ID that is not returns `404` with the code `member_not_found`, and when the Discord API is unavailable the call returns `503` with the code `discord_unavailable`. Nothing is granted in either case. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying. A successful membership lookup is cached for five minutes.\n\nThe XP, its entry in the XP history and the idempotency key are committed in a single transaction. The grant counts toward the current season when seasons are on. A grant that would take the member's XP past the largest number CEEJAY can store returns `409` with the code `xp_limit_reached`, and nothing is granted.\n\nWhen the grant takes the member up a level, CEEJAY's bot grants that level's rewards and level roles shortly afterwards. The call does not wait for it.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member, amount and reason. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is granted. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing. A body that sends `idempotency_key` here gets no key: this operation never read that spelling.", "operationId": "grantXp", "x-required-scope": [ "xp:grant" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantXpRequest" }, "examples": { "grant": { "summary": "Give 250 XP", "value": { "discordId": "409876543210987654", "amount": 250, "reason": "Completed the tutorial island", "idempotencyKey": "tutorial-409876543210987654" } } } } } }, "responses": { "200": { "description": "The XP was granted. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantXpResponse" }, "examples": { "granted": { "summary": "Granted", "value": { "success": true, "data": { "discordId": "409876543210987654", "previousXP": 8450, "xpGranted": 250, "totalXP": 8700, "previousLevel": 12, "currentLevel": 12, "leveledUp": false, "reason": "Completed the tutorial island", "auditId": "10442", "xp": 8700, "previousXp": 8450, "level": 12, "duplicate": false } } }, "repeated": { "summary": "A repeat of an earlier call", "value": { "success": true, "data": { "discordId": "409876543210987654", "previousXP": 8450, "xpGranted": 250, "totalXP": 8700, "previousLevel": 12, "currentLevel": 12, "leveledUp": false, "reason": "Completed the tutorial island", "auditId": "10442", "xp": 8700, "previousXp": 8450, "level": 12, "duplicate": true } } } } } } }, "400": { "description": "The request was rejected. Nothing was granted. The checks run in this order: the body, Discord ID, amount, maximum, a null character in the reason, a reason that is not a string, then the idempotency key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badAmount": { "summary": "Invalid amount", "value": { "error": "amount must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "tooMuch": { "summary": "Amount over the maximum", "value": { "error": "amount cannot exceed 100000", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "nullCharacter": { "summary": "A null character in the reason", "value": { "error": "reason cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badReason": { "summary": "reason is not a string", "value": { "error": "reason must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "$ref": "#/components/responses/MemberNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The `idempotencyKey` was already used by this API key for a different request (`idempotency_key_reused`: another operation, or other values), or the first request with it is still being processed (`idempotency_in_progress`: wait `retryAfter` seconds and retry). Nothing was changed by this call. Or the grant would take the member's XP past the largest number CEEJAY can store (`xp_limit_reached`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "keyReused": { "summary": "The key was already used for a different request", "value": { "error": "This idempotencyKey was already used for a different request", "code": "idempotency_key_reused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyInProgress": { "summary": "The first request with this key is still running", "value": { "error": "The first request with this idempotencyKey is still running. Try again in a few seconds.", "code": "idempotency_in_progress", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 5 } }, "xpLimit": { "summary": "The XP would not fit", "value": { "error": "This grant would take the member's XP past the largest number CEEJAY can store, so nothing was changed", "code": "xp_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "A check CEEJAY needs could not be made, and nothing was changed. Either CEEJAY has no profile for this Discord ID and could not check with Discord whether it is a member of your server (`discord_unavailable`: retry the request shortly), or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "discordUnavailable": { "summary": "Discord could not be asked", "value": { "error": "Could not check with Discord that this ID is a member of the server, so nothing was changed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/xp/deduct": { "post": { "tags": [ "XP" ], "summary": "Deduct XP", "description": "Takes XP from a member. It never takes a total below 0.\n\n**Required scope:** `xp:deduct` (a key with the `*` scope can also call it).\n\nTaking more than the member has leaves them at 0 instead of failing: `xpDeducted` says what was actually taken. Unlike Grant XP, this call does not create a profile and does not ask Discord: a member CEEJAY has not seen returns `404` with the code `member_not_found`. The XP, its history entry and the idempotency key are committed in a single transaction. The deduction is added to the audit log, and to the XP history as a negative entry when something was taken. It does not change the member's season XP.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member, amount and reason. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is taken. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing. A body that sends `idempotency_key` here gets no key: this operation never read that spelling.", "operationId": "deductXp", "x-required-scope": [ "xp:deduct" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeductXpRequest" }, "examples": { "deduct": { "summary": "Take 200 XP", "value": { "discordId": "409876543210987654", "amount": 200, "reason": "Reversed a duplicate award", "idempotencyKey": "reversal-10442" } } } } } }, "responses": { "200": { "description": "The XP was taken. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeductXpResponse" }, "examples": { "deducted": { "summary": "Deducted", "value": { "success": true, "data": { "discordId": "409876543210987654", "previousXP": 200, "xpDeducted": 200, "totalXP": 0, "previousLevel": 1, "currentLevel": 0, "reason": "Reversed a duplicate award", "auditId": "10443", "xp": 0, "previousXp": 200, "level": 0, "duplicate": false } } }, "repeated": { "summary": "A repeat of an earlier call", "value": { "success": true, "data": { "discordId": "409876543210987654", "previousXP": 200, "xpDeducted": 200, "totalXP": 0, "previousLevel": 1, "currentLevel": 0, "reason": "Reversed a duplicate award", "auditId": "10443", "xp": 0, "previousXp": 200, "level": 0, "duplicate": true } } } } } } }, "400": { "description": "The request was rejected. Nothing was taken. The checks run in this order: the body, Discord ID, amount, maximum, a null character in the reason, a reason that is not a string, then the idempotency key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badAmount": { "summary": "Invalid amount", "value": { "error": "amount must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "tooMuch": { "summary": "Amount over the maximum", "value": { "error": "amount cannot exceed 2147483647", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "nullCharacter": { "summary": "A null character in the reason", "value": { "error": "reason cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badReason": { "summary": "reason is not a string", "value": { "error": "reason must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "CEEJAY has no profile for this member on your server. Nothing was taken.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknown": { "summary": "Unknown member", "value": { "error": "Member not found", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/IdempotencyUnavailable" } } } }, "/programs": { "get": { "tags": [ "Programs" ], "summary": "List programs", "description": "Lists your community's programs, so you can find the `programId` that Grant program XP and Deduct program XP need.\n\n**Required scope:** `programs:read` (a key with the `*` scope can also call it).\n\nOnly programs whose status is `active` are returned unless you pass `status`. The program XP operations work only for a program whose status is `active`. Paged by `programId`, lowest first: send `page.nextCursor` back as `cursor` and stop when it is `null`.\n\nNever returned: who made a program, its application form, its requirements, rewards and settings, its landing page, or anything about its members but how many there are.", "operationId": "listPrograms", "x-required-scope": [ "programs:read" ], "x-since": "1.0.0", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only programs with this status, or `all` for every program. Any other value is rejected with `400`.", "schema": { "type": "string", "enum": [ "active", "draft", "paused", "archived", "all" ], "default": "active" }, "example": "active" }, { "name": "limit", "in": "query", "required": false, "description": "The page size: an integer from 1 to 100. A value above 100 is lowered to 100, and `0`, an empty value or omitting it defaults to 50. A negative number, a fraction or text is rejected with `400`.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "default": 50 }, "example": 50 }, { "$ref": "#/components/parameters/CursorQuery" } ], "responses": { "200": { "description": "A page of programs.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProgramsResponse" }, "examples": { "programs": { "summary": "One program, and no further page", "value": { "success": true, "data": [ { "programId": 3, "name": "Ambassadors", "slug": "ambassadors", "description": "Members who host events and welcome new players.", "status": "active", "type": "custom", "memberCount": 24, "maxMembers": 50, "createdAt": "2026-08-12T10:00:00.000Z" } ], "page": { "nextCursor": null, "limit": 50 } } } } } } }, "400": { "description": "`status` is not one of the listed values, `limit` is not a whole number of 0 or more, or `cursor` is not one this operation gave out.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badStatus": { "summary": "An unknown status", "value": { "error": "status must be one of active, draft, paused, archived or all", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "status" } }, "badLimit": { "summary": "Invalid limit", "value": { "error": "limit must be a whole number of 0 or more", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "limit" } }, "badCursor": { "summary": "A cursor that cannot be read", "value": { "error": "cursor is not one this request gave out", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "cursor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "Programs are not available on this instance (`not_available`, with `feature: \"programs\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAvailableErrorResponse" }, "examples": { "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "programs" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/xp/program/grant": { "post": { "tags": [ "XP" ], "summary": "Grant program XP", "description": "Grants a member XP inside a community program, such as an ambassador program. Program XP is tracked separately from the member's server-wide XP.\n\n**Required scope:** `xp:program:grant` (a key with the `*` scope can also call it).\n\nThe program must be `active` and the member must be enrolled with the status `accepted` or `active`. List programs (`GET /programs`) gives you the IDs. An enrolled ID CEEJAY has no member profile for is then looked up in Discord: an ID that is not in your server returns `404` with the code `member_not_found`, and when the Discord API is unavailable the call returns `503` with the code `discord_unavailable`. Nothing is changed in either case. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.\n\nThe XP, its line in the program's activity timeline and the idempotency key are committed in a single transaction. The grant is added to the audit log as well.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same program, member, amount and reason. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is granted. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing.", "operationId": "grantProgramXp", "x-required-scope": [ "xp:program:grant" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantProgramXpRequest" }, "examples": { "grant": { "summary": "Give 100 program XP", "value": { "programId": 3, "discordId": "409876543210987654", "amount": 100, "reason": "Hosted a community event", "idempotencyKey": "event-2026-41-host" } } } } } }, "responses": { "200": { "description": "The program XP was granted. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantProgramXpResponse" }, "examples": { "granted": { "summary": "Granted", "value": { "success": true, "data": { "programId": 3, "programName": "Ambassadors", "discordId": "409876543210987654", "previousXP": 400, "xpGranted": 100, "totalXP": 500, "reason": "Hosted a community event", "auditId": "10444", "programXp": 500, "previousProgramXp": 400, "duplicate": false } } }, "repeated": { "summary": "A repeat of an earlier call", "value": { "success": true, "data": { "programId": 3, "programName": "Ambassadors", "discordId": "409876543210987654", "previousXP": 400, "xpGranted": 100, "totalXP": 500, "reason": "Hosted a community event", "auditId": "10444", "programXp": 500, "previousProgramXp": 400, "duplicate": true } } } } } } }, "400": { "description": "The request was rejected. Nothing was changed. The checks run in this order: the body, program ID, its maximum, Discord ID, amount, its maximum, a null character in the reason, a reason that is not a string, a reason that is not well-formed Unicode, then the idempotency key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badProgram": { "summary": "Invalid program ID", "value": { "error": "programId must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "programId" } }, "programTooLarge": { "summary": "Program ID over the maximum", "value": { "error": "programId cannot exceed 2147483647", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "programId" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badAmount": { "summary": "Invalid amount", "value": { "error": "amount must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "tooMuch": { "summary": "Amount over the maximum", "value": { "error": "amount cannot exceed 100000", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "nullCharacter": { "summary": "A null character in the reason", "value": { "error": "reason cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badReason": { "summary": "reason is not a string", "value": { "error": "reason must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badUnicode": { "summary": "reason contains an unpaired surrogate", "value": { "error": "reason must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "There is no program with this ID on your server (`program_not_found`), the member is not enrolled in it (`member_not_enrolled`), the Discord ID is enrolled but is not a member of your server (`member_not_found`), or this instance does not support programs yet (`not_available`). A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noProgram": { "summary": "Program not found", "value": { "error": "Program not found", "code": "program_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notEnrolled": { "summary": "Member not enrolled", "value": { "error": "Member is not enrolled in this program", "code": "member_not_enrolled", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAMember": { "summary": "Not a member of your server", "value": { "error": "Member not found", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "programs" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The program or the member's status does not allow XP changes: the body names the status that blocked the call. Or the grant would take the member's program XP past the largest number CEEJAY can store (`xp_limit_reached`). The `idempotencyKey` was already used by this API key for a different request (`idempotency_key_reused`: another operation, or other values), or the first request with it is still being processed (`idempotency_in_progress`: wait `retryAfter` seconds and retry). Nothing was changed by this call.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramConflictErrorResponse" }, "examples": { "programNotActive": { "summary": "Program is not active", "value": { "error": "Program is not active", "code": "program_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "programStatus": "draft" } }, "memberStatus": { "summary": "Member status does not allow XP changes", "value": { "error": "Member status does not allow XP changes", "code": "member_status_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "memberStatus": "applied" } }, "xpLimit": { "summary": "The XP would not fit", "value": { "error": "This grant would take the member's XP past the largest number CEEJAY can store, so nothing was changed", "code": "xp_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyReused": { "summary": "The key was already used for a different request", "value": { "error": "This idempotencyKey was already used for a different request", "code": "idempotency_key_reused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyInProgress": { "summary": "The first request with this key is still running", "value": { "error": "The first request with this idempotencyKey is still running. Try again in a few seconds.", "code": "idempotency_in_progress", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 5 } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "A check CEEJAY needs could not be made, and nothing was changed. Either CEEJAY has no profile for this Discord ID and could not check with Discord whether it is a member of your server (`discord_unavailable`: retry the request shortly), or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "discordUnavailable": { "summary": "Discord could not be asked", "value": { "error": "Could not check with Discord that this ID is a member of the server, so nothing was changed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/xp/program/deduct": { "post": { "tags": [ "XP" ], "summary": "Deduct program XP", "description": "Takes XP from a member inside a community program. It never takes a total below 0.\n\n**Required scope:** `xp:program:deduct` (a key with the `*` scope can also call it).\n\nThe program must be `active` and the member must be enrolled with the status `accepted` or `active`. Taking more than the member has leaves them at 0: `xpDeducted` says what was actually taken. The XP, its line in the program's activity timeline and the idempotency key are committed in a single transaction. The deduction is added to the audit log as well.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same program, member, amount and reason. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is taken. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing.", "operationId": "deductProgramXp", "x-required-scope": [ "xp:program:deduct" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeductProgramXpRequest" }, "examples": { "deduct": { "summary": "Take 50 program XP", "value": { "programId": 3, "discordId": "409876543210987654", "amount": 50, "reason": "Reversed a duplicate award", "idempotencyKey": "reversal-10444" } } } } } }, "responses": { "200": { "description": "The program XP was taken. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeductProgramXpResponse" }, "examples": { "deducted": { "summary": "Deducted", "value": { "success": true, "data": { "programId": 3, "programName": "Ambassadors", "discordId": "409876543210987654", "previousXP": 500, "xpDeducted": 50, "totalXP": 450, "reason": "Reversed a duplicate award", "auditId": "10445", "programXp": 450, "previousProgramXp": 500, "duplicate": false } } }, "repeated": { "summary": "A repeat of an earlier call", "value": { "success": true, "data": { "programId": 3, "programName": "Ambassadors", "discordId": "409876543210987654", "previousXP": 500, "xpDeducted": 50, "totalXP": 450, "reason": "Reversed a duplicate award", "auditId": "10445", "programXp": 450, "previousProgramXp": 500, "duplicate": true } } } } } } }, "400": { "description": "The request was rejected. Nothing was changed. The checks run in this order: the body, program ID, its maximum, Discord ID, amount, its maximum, a null character in the reason, a reason that is not a string, a reason that is not well-formed Unicode, then the idempotency key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badProgram": { "summary": "Invalid program ID", "value": { "error": "programId must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "programId" } }, "programTooLarge": { "summary": "Program ID over the maximum", "value": { "error": "programId cannot exceed 2147483647", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "programId" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badAmount": { "summary": "Invalid amount", "value": { "error": "amount must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "tooMuch": { "summary": "Amount over the maximum", "value": { "error": "amount cannot exceed 100000", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "nullCharacter": { "summary": "A null character in the reason", "value": { "error": "reason cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badReason": { "summary": "reason is not a string", "value": { "error": "reason must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badUnicode": { "summary": "reason contains an unpaired surrogate", "value": { "error": "reason must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "There is no program with this ID on your server (`program_not_found`), the member is not enrolled in it (`member_not_enrolled`), or this instance does not support programs yet (`not_available`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noProgram": { "summary": "Program not found", "value": { "error": "Program not found", "code": "program_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notEnrolled": { "summary": "Member not enrolled", "value": { "error": "Member is not enrolled in this program", "code": "member_not_enrolled", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "programs" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The program or the member's status does not allow XP changes: the body names the status that blocked the call. Or the change would not fit the largest number CEEJAY can store (`xp_limit_reached`). The `idempotencyKey` was already used by this API key for a different request (`idempotency_key_reused`: another operation, or other values), or the first request with it is still being processed (`idempotency_in_progress`: wait `retryAfter` seconds and retry). Nothing was changed by this call.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramConflictErrorResponse" }, "examples": { "programNotActive": { "summary": "Program is not active", "value": { "error": "Program is not active", "code": "program_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "programStatus": "draft" } }, "memberStatus": { "summary": "Member status does not allow XP changes", "value": { "error": "Member status does not allow XP changes", "code": "member_status_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "memberStatus": "applied" } }, "xpLimit": { "summary": "The XP would not fit", "value": { "error": "This change would take the member's XP past the largest number CEEJAY can store, so nothing was changed", "code": "xp_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyReused": { "summary": "The key was already used for a different request", "value": { "error": "This idempotencyKey was already used for a different request", "code": "idempotency_key_reused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyInProgress": { "summary": "The first request with this key is still running", "value": { "error": "The first request with this idempotencyKey is still running. Try again in a few seconds.", "code": "idempotency_in_progress", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 5 } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/IdempotencyUnavailable" } } } }, "/economy/balance": { "get": { "tags": [ "Economy" ], "summary": "Get currency balance", "description": "Returns a member's current balance and their lifetime totals in your community's currency.\n\n**Required scope:** `economy:read` (a key with the `*` scope can also call it).\n\nA member with no balance yet is not an error: the call returns `200` with every number at `0` and `lastUpdated` as `null`. Reading creates nothing. To tell \"no account\" from \"zero balance\", call `GET /members/{discordId}`, which returns `404` for a member CEEJAY has never seen.", "operationId": "getEconomyBalance", "x-required-scope": [ "economy:read" ], "x-since": "1.0.0", "parameters": [ { "$ref": "#/components/parameters/DiscordIdQuery" } ], "responses": { "200": { "description": "The member's balance.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconomyBalanceResponse" }, "examples": { "member": { "summary": "A member with a balance", "value": { "success": true, "data": { "discordId": "409876543210987654", "balance": 2450, "totalEarned": 9100, "totalSpent": 6650, "lastUpdated": "2026-10-01T09:14:22.118Z" } } }, "noBalance": { "summary": "A member with no balance yet", "value": { "success": true, "data": { "discordId": "409876543210987654", "balance": 0, "totalEarned": 0, "totalSpent": 0, "lastUpdated": null } } } } } } }, "400": { "description": "The Discord ID is missing, not 17 to 20 digits, or was sent more than once.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "$ref": "#/components/responses/NotAvailable" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/economy/grant": { "post": { "tags": [ "Economy" ], "summary": "Grant currency", "description": "Adds currency to a member's balance.\n\n**Required scope:** `economy:grant` (a key with the `*` scope can also call it).\n\nThe member's wallet is created if they have none. An ID CEEJAY has no member profile for is looked up in Discord first: a member of your server is credited, an ID that is not in your server returns `404` with the code `member_not_found`, and when Discord cannot be reached the call returns `503` with the code `discord_unavailable`. Nothing is credited in either case. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying. A positive membership check is cached for five minutes. A repeat of a call that was already applied is handled before this lookup.\n\nThe movement is added to the member's transaction history with the `reason` you send, or `API grant`, and counts toward `totalEarned`. The grant works whether or not the community's economy is enabled.\n\nA balance cannot pass the community's maximum, which is 1,000,000 unless the community has set another. When the maximum is reached the call still succeeds: `amountGranted` is what was actually added (it can be `0`), `amountRequested` is what you asked for and `capped` is `true`. A grant that would take the member's lifetime total past the largest number CEEJAY can store returns `409` with the code `balance_limit_reached`, and nothing is credited.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the first response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member and the same amount; the note may differ. One key is one request: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing moves. A key belongs to the API key that sent it and is retained for 30 days. The key still works on an instance that is still being updated. The deprecated alias `idempotency_key` is still accepted, and is the one used when both are sent. A key CEEJAY no longer has a response for (one older than 30 days, or one sent before version 1.0.0) is still recognised from the member's transaction history, permanently: the response then includes the amount and the balance of the first call, the amount and the note you sent this time, and `capped: false`.", "operationId": "grantEconomy", "x-required-scope": [ "economy:grant" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCurrencyRequest" }, "examples": { "grant": { "summary": "Give 500 coins", "value": { "discordId": "409876543210987654", "amount": 500, "reason": "Weekly tournament prize", "idempotencyKey": "tournament-2026-40-winner" } } } } } }, "responses": { "200": { "description": "What was credited. With `duplicate: true` it is the response to an earlier call that sent the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCurrencyResponse" }, "examples": { "granted": { "summary": "Credited in full", "value": { "success": true, "data": { "discordId": "409876543210987654", "amountGranted": 500, "amountRequested": 500, "capped": false, "duplicate": false, "balance": 2950, "totalEarned": 9600, "description": "Weekly tournament prize", "reason": "Weekly tournament prize" } } }, "capped": { "summary": "Cut short by the maximum balance", "value": { "success": true, "data": { "discordId": "409876543210987654", "amountGranted": 200, "amountRequested": 500, "capped": true, "duplicate": false, "balance": 1000000, "totalEarned": 412600, "description": "Weekly tournament prize", "reason": "Weekly tournament prize" } } }, "repeated": { "summary": "A repeat of an earlier call", "value": { "success": true, "data": { "discordId": "409876543210987654", "amountGranted": 500, "amountRequested": 500, "capped": false, "duplicate": true, "balance": 2950, "totalEarned": 9600, "description": "Weekly tournament prize", "reason": "Weekly tournament prize" } } } } } } }, "400": { "description": "The request was rejected. Nothing was credited. The checks run in this order: the body, Discord ID, amount, maximum, the idempotency key, a null character in the note, then a note that is not a string. A message names the field name you sent (`reason` or `description`, `idempotencyKey` or `idempotency_key`). A repeat of a call that was already applied is handled after these, and the member is looked up last.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badAmount": { "summary": "Invalid amount", "value": { "error": "amount must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "tooMuch": { "summary": "Amount over the maximum", "value": { "error": "amount cannot exceed 1000000", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "badOlderKey": { "summary": "Invalid idempotency key, sent under its deprecated alias", "value": { "error": "idempotency_key must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotency_key" } }, "nullInReason": { "summary": "A null character in the reason", "value": { "error": "reason cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badReason": { "summary": "reason is not a string", "value": { "error": "reason must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "nullInDescription": { "summary": "A null character in the note, sent under its deprecated alias", "value": { "error": "description cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "description" } }, "badDescription": { "summary": "The note is not a string, sent under its deprecated alias", "value": { "error": "description must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "description" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "The Discord ID is not a member of your server (`member_not_found`: CEEJAY has no profile for it, and Discord says it is not in the server), or this instance has no currency yet (`not_available`). Nothing was credited. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAMember": { "summary": "Not a member of your server", "value": { "error": "Member not found", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "economy" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The `idempotencyKey` was already used by this API key for a different request (`idempotency_key_reused`: another operation, or other values), or the first request with it is still being processed (`idempotency_in_progress`: wait `retryAfter` seconds, then retry). Nothing was changed by this call. Or the grant would take the member's lifetime total past the largest number CEEJAY can store (`balance_limit_reached`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "keyReused": { "summary": "The key was already used for a different request", "value": { "error": "This idempotencyKey was already used for a different request", "code": "idempotency_key_reused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyInProgress": { "summary": "The first request with this key is still running", "value": { "error": "The first request with this idempotencyKey is still running. Try again in a few seconds.", "code": "idempotency_in_progress", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 5 } }, "balanceLimit": { "summary": "The total would not fit", "value": { "error": "This grant would take the member's total past the largest number CEEJAY can store, so nothing was changed", "code": "balance_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "A check CEEJAY needs could not be made, and nothing was changed. Either CEEJAY has no profile for this Discord ID and could not check with Discord whether it is a member of your server (`discord_unavailable`: retry shortly), or you sent a key and this instance does not support idempotency keys (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "discordUnavailable": { "summary": "Discord could not be asked", "value": { "error": "Could not check with Discord that this ID is a member of the server, so nothing was changed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/economy/deduct": { "post": { "tags": [ "Economy" ], "summary": "Deduct currency", "description": "Deducts currency from a member.\n\n**Required scope:** `economy:deduct` (a key with the `*` scope can also call it).\n\nThe balance never goes below zero. If the member's balance is less than `amount`, nothing is deducted and the call returns `400` with the code `insufficient_balance`, `balance` and `requested`. This error keeps the status `400` it has always had: match on `code`. A member with no balance at all gets the same response, with `balance` at `0`, and no balance is created for them.\n\nA deduction is not counted as the member's spending: `totalSpent` does not change. The movement is added to the member's transaction history with the `reason` you send, or `API deduction`. The deduction works whether or not the community's economy is enabled.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the first response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member and the same amount; the note may differ. One key is one request: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing moves. A key belongs to the API key that sent it and is retained for 30 days. The key still works on an instance that is still being updated. The deprecated alias `idempotency_key` is still accepted, and is the one used when both are sent. A key CEEJAY no longer has a response for (one older than 30 days, or one sent before version 1.0.0) is still recognised from the member's transaction history, permanently: the response then includes the amount and the balance of the first call, and the note you sent this time.", "operationId": "deductEconomy", "x-required-scope": [ "economy:deduct" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeductCurrencyRequest" }, "examples": { "deduct": { "summary": "Take 200 coins", "value": { "discordId": "409876543210987654", "amount": 200, "reason": "Season pass", "idempotencyKey": "order-88213-deduct" } } } } } }, "responses": { "200": { "description": "What was deducted. With `duplicate: true` it is the response to an earlier call that sent the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeductCurrencyResponse" }, "examples": { "deducted": { "summary": "Deducted", "value": { "success": true, "data": { "discordId": "409876543210987654", "amountDeducted": 200, "duplicate": false, "balance": 2250, "description": "Season pass", "reason": "Season pass" } } }, "repeated": { "summary": "A repeat of an earlier call", "value": { "success": true, "data": { "discordId": "409876543210987654", "amountDeducted": 200, "duplicate": true, "balance": 2250, "description": "Season pass", "reason": "Season pass" } } } } } } }, "400": { "description": "The request was rejected. Nothing was deducted. The checks run in this order: the body, Discord ID, amount, maximum, the idempotency key, a null character in the note, a note that is not a string, then the balance. A message names the field name you sent.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeductCurrencyErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badAmount": { "summary": "Invalid amount", "value": { "error": "amount must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "tooMuch": { "summary": "Amount over the maximum", "value": { "error": "amount cannot exceed 2147483647", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "amount" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "badOlderKey": { "summary": "Invalid idempotency key, sent under its deprecated alias", "value": { "error": "idempotency_key must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotency_key" } }, "nullInReason": { "summary": "A null character in the reason", "value": { "error": "reason cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "badReason": { "summary": "reason is not a string", "value": { "error": "reason must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "reason" } }, "nullInDescription": { "summary": "A null character in the note, sent under its deprecated alias", "value": { "error": "description cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "description" } }, "badDescription": { "summary": "The note is not a string, sent under its deprecated alias", "value": { "error": "description must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "description" } }, "insufficient": { "summary": "The member's balance is less than the amount", "value": { "error": "Insufficient balance", "code": "insufficient_balance", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "currentBalance": 120, "requested": 500, "balance": 120 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "$ref": "#/components/responses/NotAvailable" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "You sent an `idempotencyKey`, and this instance does not support idempotency keys (`idempotency_unavailable`). Nothing was changed. Waiting does not change this response: contact support to finish the update, or send the request without a key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/shop/purchases": { "get": { "tags": [ "Shop" ], "summary": "List shop purchases", "description": "Lists the purchases, and the rewards members earned, that are delivered by your API and have not yet been confirmed by your server.\n\n**Required scope:** `shop:fulfil` (a key with the `*` scope can also call it).\n\nA purchase is in one of two states. `processing`: your server responded to the delivery with pending, and CEEJAY is awaiting Complete a shop delivery. `retrying`: the delivery failed and CEEJAY tries it again every hour. A purchase in `processing` is never sent again, so this list is how a server that lost a delivery learns of it. Finish each one with `POST /shop/purchases/{purchaseId}/complete`.\n\nA purchase made through a game names the player in `player`, as the delivery did, so an item that was lost on the way can still be delivered to the right player.\n\nPaged by `purchaseId`, oldest first: send `page.nextCursor` back as `cursor` and stop when it is `null`. Polling once a minute uses one of a key's requests a minute.\n\nNever returned: the item's delivery URL, its signing secret or the rest of its settings, the text of the last delivery error, team notes, member names and avatars, or purchases of items that are not delivered by your API.", "operationId": "listShopPurchases", "x-required-scope": [ "shop:fulfil" ], "x-since": "1.0.0", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Which purchases to list. Only `waiting` exists today, and it is the default. Any other value is rejected with `400`.", "schema": { "type": "string", "enum": [ "waiting" ], "default": "waiting" }, "example": "waiting" }, { "name": "limit", "in": "query", "required": false, "description": "The page size: an integer from 1 to 100. A value above 100 is lowered to 100, and `0`, an empty value or omitting it defaults to 50. A negative number, a fraction or text is rejected with `400`.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "default": 50 }, "example": 50 }, { "$ref": "#/components/parameters/CursorQuery" } ], "responses": { "200": { "description": "A page of waiting purchases.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListShopPurchasesResponse" }, "examples": { "waiting": { "summary": "One purchase awaiting your confirmation, and one being retried", "value": { "success": true, "data": [ { "purchaseId": 4411, "deliveryId": "shop_4411", "event": "shop.purchase", "state": "processing", "item": { "id": 12, "name": "Gold pack", "itemKey": "gold_500" }, "discordId": "234567890123456789", "pricePaid": 500, "createdAt": "2026-10-07T18:00:00.000Z", "pendingSince": "2026-10-07T18:00:02.000Z", "completeBy": "2026-10-08T18:00:02.000Z", "attempts": 1, "lastAttemptAt": "2026-10-07T18:00:02.000Z", "answer": null, "input": null, "player": { "game": "rugby_manager", "playerId": "p_19", "proof": "verified" } }, { "purchaseId": 4412, "deliveryId": "shop_4412", "event": "reward.earned", "state": "retrying", "item": { "id": null, "name": "Founder skin", "itemKey": "skin_founder" }, "discordId": "234567890123456789", "pricePaid": 0, "createdAt": "2026-10-07T18:20:00.000Z", "pendingSince": null, "completeBy": null, "attempts": 2, "lastAttemptAt": "2026-10-07T19:20:04.000Z", "answer": null, "input": null, "player": null, "reward": { "id": 31, "sourceKind": "level", "sourceId": "10", "sourceLabel": "Level 10" } } ], "page": { "nextCursor": null, "limit": 50 } } } } } } }, "400": { "description": "`status` is not `waiting`, `limit` is not a whole number of 0 or more, or `cursor` is not one this operation gave out.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badStatus": { "summary": "A status other than waiting", "value": { "error": "status must be 'waiting'", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "status" } }, "badLimit": { "summary": "Invalid limit", "value": { "error": "limit must be a whole number of 0 or more", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "limit" } }, "badCursor": { "summary": "A cursor that cannot be read", "value": { "error": "cursor is not one this request gave out", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "cursor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "Shop delivery is not available on this instance (`not_available`, with `feature: \"shopDelivery\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAvailableErrorResponse" }, "examples": { "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "shopDelivery" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/shop/purchases/{purchaseId}/complete": { "post": { "tags": [ "Shop" ], "summary": "Complete a shop delivery", "description": "Tells CEEJAY how a \"Delivered by your API\" shop purchase ended, when your endpoint did not respond to the delivery request immediately.\n\n**Required scope:** `shop:fulfil` (a key with the `*` scope can also call it).\n\nUse it after CEEJAY sent you a delivery request (the `shop.purchase` webhook in this document) and your endpoint responded with `202` or `{ \"status\": \"pending\" }`, or while CEEJAY is waiting to retry the delivery. It works on purchases of your server whose item is delivered by your API, while their status is Being delivered or waiting for a retry. It also works on a reward a member earned that is set to be delivered by your API (the `reward.earned` webhook). List shop purchases (`GET /shop/purchases`) lists the ones that await your confirmation.\n\n`delivered` marks the purchase fulfilled. `failed` refunds the member and lets the team know, and `message` is shown to them. An earned reward was not paid for, so `failed` marks it failed and refunds nothing.\n\nSending the same request again is safe: the call returns `200` with `alreadyDone: true`. Sending the opposite status to a purchase that has already reached a final status returns `409` with the code `wrong_status`. A purchase that is still pending after 24 hours is refunded by CEEJAY.\n\nA body that is not a JSON object is read as an empty one, so it returns the `status` message.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same purchase, status and message. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is changed. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing. A second completion of a purchase is the same change, so when a first request was started more than a minute ago and never finished, a retry with the same key is processed again and returns normally.", "operationId": "completeShopPurchase", "x-required-scope": [ "shop:fulfil" ], "x-since": "1.0.0", "parameters": [ { "$ref": "#/components/parameters/PurchaseIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteShopPurchaseRequest" }, "examples": { "delivered": { "summary": "Delivered", "value": { "status": "delivered" } }, "failed": { "summary": "Could not deliver", "value": { "status": "failed", "message": "The player has no account on this realm" } } } } } }, "responses": { "200": { "description": "The purchase was updated, or was already in the state you asked for.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteShopPurchaseResponse" }, "examples": { "fulfilled": { "summary": "Delivered", "value": { "success": true, "purchaseId": 4242, "status": "fulfilled", "data": { "purchaseId": 4242, "status": "fulfilled", "alreadyDone": false, "refunded": null, "duplicate": false } } }, "refunded": { "summary": "Failed, member refunded", "value": { "success": true, "purchaseId": 4242, "status": "refunded", "refunded": 500, "data": { "purchaseId": 4242, "status": "refunded", "alreadyDone": false, "refunded": 500, "duplicate": false } } }, "failedReward": { "summary": "Failed, for a reward a member earned", "value": { "success": true, "purchaseId": 4243, "status": "failed", "data": { "purchaseId": 4243, "status": "failed", "alreadyDone": false, "refunded": null, "duplicate": false } } }, "repeated": { "summary": "You had already sent this request", "value": { "success": true, "purchaseId": 4242, "status": "fulfilled", "alreadyDone": true, "data": { "purchaseId": 4242, "status": "fulfilled", "alreadyDone": true, "refunded": null, "duplicate": false } } } } } } }, "400": { "description": "The purchase ID is not a whole number or is above 2,147,483,647, the body is not valid, or CEEJAY's bot rejected the request (the last example).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badId": { "summary": "Purchase ID not a number", "value": { "error": "A numeric purchase id is required", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "purchaseId" } }, "idTooLarge": { "summary": "Purchase ID over the maximum", "value": { "error": "The purchase id cannot exceed 2147483647", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "purchaseId" } }, "badStatus": { "summary": "Unknown status", "value": { "error": "status must be 'delivered' or 'failed'", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "status" } }, "badMessage": { "summary": "Note not text", "value": { "error": "message must be text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "message" } }, "longMessage": { "summary": "Note too long", "value": { "error": "message must be 500 characters or fewer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "message" } }, "nullInMessage": { "summary": "A null character in the note", "value": { "error": "message cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "message" } }, "halfPairInMessage": { "summary": "An unpaired surrogate in the note", "value": { "error": "message must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "message" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "refused": { "summary": "Rejected by the bot", "value": { "error": "The request was not valid", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "There is no purchase with this ID on your server that is delivered by your API (`purchase_not_found`), or this instance does not support shop delivery yet (`not_available`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noPurchase": { "summary": "Purchase not found", "value": { "error": "Purchase not found", "code": "purchase_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gone": { "summary": "The purchase disappeared while being updated", "value": { "error": "This purchase no longer exists on this server", "code": "purchase_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "shopDelivery" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The purchase has already changed status, so it cannot be marked this way (`wrong_status`): `status` is its current status. The `idempotencyKey` was already used by this API key for a different request (`idempotency_key_reused`: another operation, or other values), or the first request with it is still being processed (`idempotency_in_progress`: wait `retryAfter` seconds and retry). Nothing was changed by this call.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseErrorResponse" }, "examples": { "wrongStatus": { "summary": "Already refunded", "value": { "error": "This purchase is refunded and can no longer be marked delivered", "code": "wrong_status", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "status": "refunded" } }, "movedOn": { "summary": "Status changed while being updated", "value": { "error": "This reward's status has already changed", "code": "wrong_status", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "status": null } }, "keyReused": { "summary": "The key was already used for a different request", "value": { "error": "This idempotencyKey was already used for a different request", "code": "idempotency_key_reused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyInProgress": { "summary": "The first request with this key is still running", "value": { "error": "The first request with this idempotencyKey is still running. Try again in a few seconds.", "code": "idempotency_in_progress", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 5 } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "CEEJAY's bot, which finishes the purchase, could not be reached or could not finish. Send the same request again: it is safe to repeat.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unreachable": { "summary": "The bot could not finish", "value": { "error": "The delivery could not be finished. Try again", "code": "bot_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "$ref": "#/components/responses/IdempotencyUnavailable" }, "504": { "description": "CEEJAY's bot did not respond in time. Send the same request again: it is safe to repeat.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "timeout": { "summary": "The bot timed out", "value": { "error": "The bot did not answer in time. Send the same request again: it is safe to repeat", "code": "bot_timeout", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/quests/list": { "get": { "tags": [ "Quests" ], "summary": "List quests", "description": "Lists the quests set up on your server, with their rewards and completion rules.\n\n**Required scope:** `quests:read` (a key with the `*` scope can also call it).\n\nOnly quests whose status is `active` are returned unless you pass `status`. They are ordered by the sort order set in the dashboard, then newest first.\n\n**Paging.** There are two ways to page; send one of them. With `cursor`, send the `page.nextCursor` of the page before and stop when it is `null`: every quest comes back once, also when quests are added while you page. With `offset`, skip a number of quests, as before. When both are sent the page starts at `cursor` and `offset` is not used. `total`, `limit` and `offset` are returned alongside `data` in every response.\n\nEach quest includes the rules Complete a quest applies to it: `status`, `startsAt`, `endsAt`, `isRepeatable`, `maxCompletions`, `maxCompletionsPerMember`, `repeatCooldownHours`, `requiredLevel`, `requiredRoleId`, `prerequisiteQuestId`, `requiredSeasonXp` and `programId`. The community's daily quest limit is in Community details (`GET /community`).", "operationId": "listQuests", "x-required-scope": [ "quests:read" ], "x-since": "1.0.0", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only quests with this status, for example `draft`, `paused` or `archived`. It is not checked against a list. Defaults to `active`. A null character (`%00`) in it is rejected with `400`.", "schema": { "type": "string", "default": "active" }, "example": "active" }, { "name": "category", "in": "query", "required": false, "description": "Only quests in this category. A null character (`%00`) in it is rejected with `400`.", "schema": { "type": "string" }, "example": "integrations" }, { "name": "limit", "in": "query", "required": false, "description": "The page size: an integer from 1 to 100. A value above 100 is lowered to 100, and `0`, an empty value or omitting it defaults to 50. A negative number, a fraction or text is rejected with `400`.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "default": 50 }, "example": 20 }, { "name": "offset", "in": "query", "required": false, "description": "How many quests to skip: an integer from 0 to 2,147,483,647. Not used when `cursor` is sent. A negative number, a fraction, text or a larger number is rejected with `400`.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "default": 0 }, "example": 0 }, { "$ref": "#/components/parameters/CursorQuery" } ], "responses": { "200": { "description": "A page of quests. `page` says whether there is a next one. `total`, `limit` and `offset` are returned alongside `data`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListQuestsResponse" }, "examples": { "page": { "summary": "One quest, and no further page", "value": { "success": true, "total": 1, "limit": 20, "offset": 0, "data": [ { "id": 42, "title": "Join the weekend tournament", "description": "Play one match in the weekend tournament.", "icon_emoji": "🏆", "category": "integrations", "quest_type": "api_check", "xp_reward": 500, "currency_reward": 250, "role_reward_id": "982371004827100394", "badge_id": 7, "is_repeatable": false, "max_completions": null, "max_completions_per_user": 1, "starts_at": null, "ends_at": null, "status": "active", "verification_type": "api", "program_id": null, "created_at": "2026-09-02T12:00:00.000Z", "repeat_cooldown_hours": null, "required_level": 5, "required_role_id": null, "prerequisite_quest_id": null, "required_season_xp": null, "iconEmoji": "🏆", "questType": "api_check", "xpReward": 500, "currencyReward": 250, "roleRewardId": "982371004827100394", "badgeId": 7, "isRepeatable": false, "maxCompletions": null, "maxCompletionsPerMember": 1, "startsAt": null, "endsAt": null, "verificationType": "api", "programId": null, "createdAt": "2026-09-02T12:00:00.000Z", "repeatCooldownHours": null, "requiredLevel": 5, "requiredRoleId": null, "prerequisiteQuestId": null, "requiredSeasonXp": null } ], "page": { "nextCursor": null, "limit": 20 } } } } } } }, "400": { "description": "`limit` or `offset` is not a whole number of 0 or more, or `offset` is above 2,147,483,647. A `limit` or `offset` sent more than once is rejected too. So is a `status` or a `category` that contains a null character (U+0000, `%00` in the URL), and a `cursor` that was not returned by List quests.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badLimit": { "summary": "Invalid limit", "value": { "error": "limit must be a whole number of 0 or more", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "limit" } }, "badOffset": { "summary": "Invalid offset", "value": { "error": "offset must be a whole number from 0 to 2147483647", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "offset" } }, "nullInStatus": { "summary": "A null character in the status", "value": { "error": "status cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "status" } }, "nullInCategory": { "summary": "A null character in the category", "value": { "error": "category cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "category" } }, "badCursor": { "summary": "A cursor that cannot be read", "value": { "error": "cursor cannot be read. Send page.nextCursor as it was answered", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "cursor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "$ref": "#/components/responses/NotAvailable" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/quests/complete": { "post": { "tags": [ "Quests" ], "summary": "Complete a quest", "description": "Marks a quest completed for a member and grants the quest's rewards.\n\n**Required scope:** `quests:complete` (a key with the `*` scope can also call it).\n\n**What it checks.** The quest must exist on your server. The call then applies the quest's own rules, the ones CEEJAY applies when a member does the quest in Discord, in this order, and the first one that is not met is the one returned: `quest_not_active` (`400`), `quest_not_started`, `quest_ended`, `quest_requires_role`, `quest_requires_level`, `quest_requires_season_xp`, `quest_requires_program`, `quest_full`, `quest_already_completed` (`400`), `quest_limit_reached` (`400`), `quest_cooling_down`, `quest_requires_quest`, `quest_daily_limit_reached`. A rule that is not met returns `409` with a `code` that identifies it, and nothing is completed. Three of them keep the status `400` they have always had (marked in the list): match on the code, not the status. List quests returns each quest's rules, so you can look before you call. The quest's own verification and review are not run: when you call, you are vouching that the member did the quest.\n\n**The daily quest limit.** Your community's daily quest limit (5 unless the community set another; Community details reports it) counts the quests a member completes in one UTC day, across all quests. It is a rule about starting: it is applied when the member has no open run of this quest, and a run they started in Discord before they reached the limit still completes.\n\nThe role a quest requires is read from Discord. When Discord cannot be reached for it, the call returns `503` with the code `member_roles_unavailable` and completes nothing.\n\n**The member.** An ID CEEJAY has no member profile for is looked up in Discord first. A member of your server is completed for, and gets a profile from the XP and a balance from the currency. An ID that is not in your server returns `404` with the code `member_not_found`, and when the Discord API is unavailable the call returns `503` with the code `discord_unavailable`. Nothing is written in either case. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.\n\n**A completion is a single transaction.** The completion, the XP, the currency, the badge, the program XP and the idempotency key are committed in a single transaction: a call that fails part of the way leaves nothing behind, so it can be sent again. Concurrent requests for the same member and quest are processed one at a time, so they cannot both pass the checks. When the member has an open run of the quest (one they started in Discord, in progress or waiting for review), that run is completed. A new run is added only when there is none. A completion that takes the last place of a quest with an overall limit ends the quest.\n\n**Rewards in the response.** XP is granted the same way as `POST /xp/grant`. Currency is credited up to the community's maximum balance; while the community's economy is disabled the quest's coins are not granted, and `rewards.currencySkipped` is `true`. The quest's badge is awarded if the member does not have it yet. A quest in a program adds its XP to the member's score in that program (`rewards.programXp`).\n\n**What happens after the response.** CEEJAY's bot then assigns the quest's role (`rewards.roleId`), grants the extra rewards set on the quest in the Rewards Engine, grants level rewards and assigns level roles, and sends the `quest.completed` webhook. The call does not wait for it, and returns `200` when the bot is down: these steps run once the bot is back online. If you call Grant a role, Grant program XP or Grant currency yourself after a completion to add what this operation used to leave out, stop doing that: the member would now get it twice.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member, quest and proof, and the key protects the whole completion: its XP, badge and program XP as well as its currency. A retry returns the original response even when the quest has ended or reached a limit since. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is completed. A key is scoped to the API key that sent it and is retained for 30 days. The key keeps working on an instance that has not been updated yet. The deprecated alias `idempotency_key` is still accepted, and is the one used when both are sent. A completion that granted coins is also recognised from the member's transaction history when CEEJAY no longer stores its response (a key older than 30 days, or one sent before version 1.0.0): the response then includes the coins and the balance of the first call and the quest as it is now. Without a key, a second call is a new completion and is checked like one.\n\n**Tasks your platform checks.** To report that a member did something your platform checks, for a quest task of the type Completed by your API, use `POST /quests/tasks/complete` (Complete a quest task) instead.", "operationId": "completeQuest", "x-required-scope": [ "quests:complete" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestRequest" }, "examples": { "complete": { "summary": "Complete a quest with proof", "value": { "discordId": "409876543210987654", "questId": 42, "proof": { "matchId": "m-88213", "score": 14 }, "idempotencyKey": "match-m-88213" } } } } } }, "responses": { "200": { "description": "The quest was completed and its rewards were granted. With `duplicate: true`, this is the response to an earlier call with the same `idempotencyKey`: nothing was completed or granted this time.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestResponse" }, "examples": { "completed": { "summary": "Completed", "value": { "success": true, "data": { "discordId": "409876543210987654", "questId": 42, "questTitle": "Join the weekend tournament", "status": "completed", "rewards": { "xp": 500, "currency": 250, "roleId": "982371004827100394", "badgeId": 7, "currencyRequested": 250, "currencyCapped": false, "balance": 2700, "programXp": 0 }, "progress": { "id": 9012, "server_id": "721104938271003842", "user_id": "409876543210987654", "quest_id": 42, "status": "completed", "progress_data": {}, "submission_data": { "matchId": "m-88213", "score": 14 }, "review_note": null, "reviewed_by": null, "completed_at": "2026-10-01T09:14:22.118Z", "created_at": "2026-10-01T09:14:22.118Z", "updated_at": "2026-10-01T09:14:22.118Z" }, "duplicate": false, "run": { "id": "9012", "status": "completed", "startedAt": "2026-10-01T09:14:22.118Z", "completedAt": "2026-10-01T09:14:22.118Z" } } } }, "repeated": { "summary": "A repeat of an earlier call", "value": { "success": true, "data": { "discordId": "409876543210987654", "questId": 42, "questTitle": "Join the weekend tournament", "status": "completed", "rewards": { "xp": 500, "currency": 250, "roleId": "982371004827100394", "badgeId": 7, "currencyRequested": 250, "currencyCapped": false, "balance": 2700, "programXp": 0 }, "progress": { "id": 9012, "server_id": "721104938271003842", "user_id": "409876543210987654", "quest_id": 42, "status": "completed", "progress_data": {}, "submission_data": { "matchId": "m-88213", "score": 14 }, "review_note": null, "reviewed_by": null, "completed_at": "2026-10-01T09:14:22.118Z", "created_at": "2026-10-01T09:14:22.118Z", "updated_at": "2026-10-01T09:14:22.118Z" }, "duplicate": true, "run": { "id": "9012", "status": "completed", "startedAt": "2026-10-01T09:14:22.118Z", "completedAt": "2026-10-01T09:14:22.118Z" } } } }, "coinsSkipped": { "summary": "Completed while the community's economy is disabled", "value": { "success": true, "data": { "discordId": "409876543210987654", "questId": 42, "questTitle": "Join the weekend tournament", "status": "completed", "rewards": { "xp": 500, "currency": 0, "roleId": "982371004827100394", "badgeId": 7, "currencySkipped": true, "programXp": 0 }, "progress": { "id": 9012, "server_id": "721104938271003842", "user_id": "409876543210987654", "quest_id": 42, "status": "completed", "progress_data": {}, "submission_data": { "matchId": "m-88213", "score": 14 }, "review_note": null, "reviewed_by": null, "completed_at": "2026-10-01T09:14:22.118Z", "created_at": "2026-10-01T09:14:22.118Z", "updated_at": "2026-10-01T09:14:22.118Z" }, "duplicate": false, "run": { "id": "9012", "status": "completed", "startedAt": "2026-10-01T09:14:22.118Z", "completedAt": "2026-10-01T09:14:22.118Z" } } } } } } } }, "400": { "description": "The request was rejected. Nothing was completed or granted. The first checks run in this order: the body, Discord ID, quest ID, the idempotency key, a null character in the proof, a proof nested more than 32 levels deep, then a proof that is not well-formed Unicode. After those, three of the quest's rules return this status, as they always have: `quest_not_active`, `quest_already_completed` and `quest_limit_reached`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestRefusalResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badQuest": { "summary": "Quest ID missing, or not a number or a string of digits", "value": { "error": "questId must be a number", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "questId" } }, "questNotWhole": { "summary": "Quest ID zero, negative, with a fraction, or written with a leading zero", "value": { "error": "questId must be a positive integer", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "questId" } }, "questTooLarge": { "summary": "Quest ID over the maximum", "value": { "error": "questId cannot exceed 2147483647", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "questId" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "badOlderKey": { "summary": "Invalid idempotency key, sent under its deprecated alias", "value": { "error": "idempotency_key must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotency_key" } }, "nullInProof": { "summary": "A null character in the proof", "value": { "error": "proof cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "proof" } }, "proofTooDeep": { "summary": "A proof nested more than 32 levels deep", "value": { "error": "proof is nested too deeply", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "proof" } }, "proofBadUnicode": { "summary": "A proof that contains an unpaired surrogate", "value": { "error": "proof must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "proof" } }, "notActive": { "summary": "Quest is not active", "value": { "error": "Quest is not active (status: draft)", "code": "quest_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "alreadyDone": { "summary": "Already completed", "value": { "error": "Quest already completed and is not repeatable", "code": "quest_already_completed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "limitReached": { "summary": "Per-member limit reached", "value": { "error": "Max completions per user reached", "code": "quest_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "There is no quest with this ID on your server (`quest_not_found`), the Discord ID is not a member of your server (`member_not_found`), or this instance does not support quests yet (`not_available`). Nothing was completed. A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noQuest": { "summary": "Quest not found", "value": { "error": "Quest not found", "code": "quest_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAMember": { "summary": "Not a member of your server", "value": { "error": "Member not found", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "quests" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "One of the quest's rules is not met, and nothing was completed: `code` names the rule, and some add the state that caused them. Or a reward would not fit the largest number CEEJAY can store (`xp_limit_reached`, `balance_limit_reached`). The `idempotencyKey` was already used by this API key for a different request (`idempotency_key_reused`: another operation, or other values), or the first request with it is still being processed (`idempotency_in_progress`: wait `retryAfter` seconds and retry). Nothing was changed by this call.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestRefusalResponse" }, "examples": { "notStarted": { "summary": "Before the quest's start date", "value": { "error": "Quest has not started yet", "code": "quest_not_started", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "startsAt": "2026-11-01T00:00:00.000Z" } }, "ended": { "summary": "After the quest's end date", "value": { "error": "Quest has ended", "code": "quest_ended", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "endsAt": "2026-09-30T23:59:59.000Z" } }, "requiresRole": { "summary": "Required role missing", "value": { "error": "The member does not have the role this quest requires", "code": "quest_requires_role", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "requiredRoleId": "982371004827100394" } }, "requiresLevel": { "summary": "Required level not reached", "value": { "error": "The member has not reached the level this quest requires", "code": "quest_requires_level", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "requiredLevel": 10, "level": 7 } }, "requiresSeasonXp": { "summary": "Season XP not earned", "value": { "error": "The member has not earned the season XP this quest requires", "code": "quest_requires_season_xp", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "requiredSeasonXp": 500, "seasonXp": 120, "seasonRunning": true } }, "requiresProgram": { "summary": "Not in the quest's program", "value": { "error": "The member is not in the program this quest belongs to", "code": "quest_requires_program", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "programId": 3 } }, "full": { "summary": "Overall limit reached", "value": { "error": "Quest has reached its completion limit", "code": "quest_full", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "maxCompletions": 100 } }, "coolingDown": { "summary": "Too soon after the last run", "value": { "error": "The member has to wait before completing this quest again", "code": "quest_cooling_down", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "availableAt": "2026-10-08T09:14:22.118Z" } }, "requiresQuest": { "summary": "Earlier quest not completed", "value": { "error": "The member has not completed the quest that comes before this one", "code": "quest_requires_quest", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "prerequisiteQuestId": 41 } }, "dailyLimit": { "summary": "Daily quest limit reached", "value": { "error": "The member has reached this community's daily quest limit", "code": "quest_daily_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "dailyQuestLimit": 5, "completedToday": 5, "resetsAt": "2026-10-02T00:00:00.000Z" } }, "xpLimit": { "summary": "The XP would not fit", "value": { "error": "This grant would take the member's XP past the largest number CEEJAY can store, so nothing was changed", "code": "xp_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "balanceLimit": { "summary": "The total would not fit", "value": { "error": "This grant would take the member's total past the largest number CEEJAY can store, so nothing was changed", "code": "balance_limit_reached", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyReused": { "summary": "The key was already used for a different request", "value": { "error": "This idempotencyKey was already used for a different request", "code": "idempotency_key_reused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keyInProgress": { "summary": "The first request with this key is still running", "value": { "error": "The first request with this idempotencyKey is still running. Try again in a few seconds.", "code": "idempotency_in_progress", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 5 } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "A check CEEJAY needs could not be made, and nothing was changed. CEEJAY has no profile for this Discord ID and could not check with Discord whether it is a member of your server (`discord_unavailable`); the quest requires a role and the member's roles could not be read from Discord (`member_roles_unavailable`); or you sent a key for a quest that pays coins and this CEEJAY cannot keep one in any way (`idempotency_unavailable`). For the first two, retry the request shortly.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "discordUnavailable": { "summary": "Discord could not be asked", "value": { "error": "Could not check with Discord that this ID is a member of the server, so nothing was changed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "rolesUnavailable": { "summary": "The member's roles could not be read", "value": { "error": "Could not read this member's roles from Discord, so the quest was not completed", "code": "member_roles_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/quests/tasks/complete": { "post": { "tags": [ "Quests" ], "summary": "Complete a quest task", "description": "Tells CEEJAY that a member did something your own platform checks. CEEJAY completes the quest task of the type Completed by your API that has your `taskKey`. When that was the quest's last task, it completes the quest and grants its rewards.\n\n**Required scope:** `quests:complete` (a key with the `*` scope can also call it).\n\n**Who.** Send one of `discordId`, `playerId` with `platform`, `xHandle`, `wallet`, `github` and `twitch`. With more than one, CEEJAY uses the first in that order. A `discordId` that is `null` or an empty string is skipped, and the next one is used. A `discordId` CEEJAY has a member profile for is used as it is. One it has no profile for is looked up in Discord first: an ID that is not a member of your server returns `202` with `matched: 0`, like any identifier that does not match a member, and when the Discord API is unavailable the call returns `503` with the code `discord_unavailable` and nothing happens. `playerId` is the member's ID in your game on `platform`, as you linked it with `POST /members/link`; a platform your community does not know returns `400` with the code `unknown_platform`. The others are strings, or whole numbers that are read as their digits, and must match an account the member connected in your community, which you can also set with `POST /members/link` under the platform `twitter`, `metamask`, `github` or `twitch`. When CEEJAY finds no member it returns `202` with `matched: 0`, not an error, and says nothing else about the member, so that nobody can work out who is in your community by trying names.\n\n**What it does.** CEEJAY completes every task of that type whose key is your `taskKey`, in every quest on your server that is active and inside its dates, applying the quest's own rules: the role it requires, the member's level and season XP, program, prerequisite quest, the wait between runs, the per-member and overall limits and the community's daily quest limit. A quest whose key does not match is never started. A quest that requires a role is completed only for a member who has it; a member who already has a run of that quest open is not checked again. When a rule blocks a quest, the call still returns `200` with that quest omitted. CEEJAY does not check that what you report is true, or that a key belongs to one task only: a key shared by several tasks completes all of them. When the last task of a quest is done, the quest completes and grants XP, coins, the badge, the role and any extra rewards set on it in the Rewards Engine, and `quest.completed` is sent to your webhooks.\n\nWhen a matching quest requires a role and CEEJAY's bot cannot read the member's roles from Discord, nothing is started or completed and the call returns `503` with the code `discord_unavailable`: retry shortly.\n\n**Review.** If the task's own review switch is on, or you send `review: true`, nothing completes yet. The report waits in the Review Queue, with `evidence` as the proof, until a moderator approves or rejects it, and the quest is listed in `data.sentForReview`. While it is awaiting review, the quest's other automatic tasks do not advance for that member.\n\n**The body.** A body that is not a JSON object is read as an empty one, so it returns the `taskKey` message.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. A key is stored only when the call changed something: a `200` in which at least one quest was completed or sent for review. A retry then returns the original response, with `data.duplicate: true` and the header `Idempotent-Replayed: true`. A `202` and a `200` with both lists empty store no key, so a retry with the same key is processed as a new request, for example after the player has linked the account. When CEEJAY's bot does not respond in time, or its response is lost (`502` with the code `bot_timeout`), the task may or may not have been completed. `502` with the code `bot_unavailable` is the other case: the bot never received the task or rejected it, no changes were made, and the key is released. Sending it again without a key is safe for a quest a member can complete once, and can complete a repeatable quest a second time. With a key it is never sent to the bot twice: the same key returns `409` with the code `idempotency_in_progress` for a minute, and `idempotency_outcome_unknown` after that. Each key is tied to one request payload: the same key on another operation, or with other values, returns `409` with the code `idempotency_key_reused`. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable`. A body that sends `idempotency_key` gets no key: this operation never read that spelling.", "operationId": "completeQuestTask", "x-required-scope": [ "quests:complete" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestTaskRequest" }, "examples": { "byDiscordId": { "summary": "Name the member by Discord ID, with a link as evidence", "value": { "taskKey": "tk_4k2m9x7qzb", "discordId": "409876543210987654", "evidence": "https://acme.example/players/nova/tutorial", "idempotencyKey": "tutorial-88213004" } }, "byPlayerId": { "summary": "Name the member by their ID in your game", "value": { "taskKey": "tk_4k2m9x7qzb", "playerId": "88213004", "platform": "roblox" } }, "byXHandle": { "summary": "Name the member by the X account they connected", "value": { "taskKey": "tk_4k2m9x7qzb", "xHandle": "@novaplays" } }, "forReview": { "summary": "Ask for a moderator to look at it first", "value": { "taskKey": "tk_7d3p1w8hfa", "github": "novaplays", "evidence": "https://github.com/acme/game/pull/128", "review": true } } } } } }, "responses": { "200": { "description": "The report reached CEEJAY's bot, which completes quests. `data.completed` lists the quests this call finished and `data.sentForReview` the ones whose task went to review. Both are empty when the task was completed but the quest has more tasks, when a rule stopped the completion and when no task had the key: the call does not say which.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestTaskResponse" }, "examples": { "finishedQuest": { "summary": "The task was the last one, so the quest completed", "value": { "success": true, "matched": 1, "completed": [ { "questId": 42, "title": "Finish the Acme tutorial" } ], "data": { "matched": 1, "completed": [ { "questId": 42, "questTitle": "Finish the Acme tutorial" } ], "sentForReview": [], "duplicate": false } } }, "sentForReview": { "summary": "The report went to the Review Queue", "value": { "success": true, "matched": 1, "completed": [], "data": { "matched": 1, "completed": [], "sentForReview": [ { "questId": 57, "questTitle": "Merge a pull request" } ], "duplicate": false } } }, "noQuestFinished": { "summary": "No quest finished by this call", "value": { "success": true, "matched": 1, "completed": [], "data": { "matched": 1, "completed": [], "sentForReview": [], "duplicate": false } } } } } } }, "202": { "description": "CEEJAY found no member for the identifier. No changes were made, and no idempotency key is stored. A `discordId` that is not a string of 17 to 20 digits returns this too (a JSON number is never converted to a string), and so does an identifier that is empty or `null`, or that is neither a string nor a whole number up to 9007199254740991. A `discordId` CEEJAY has no member profile for that is not a member of your server in Discord returns it as well. One exception: a `discordId` that is `null` or empty is skipped when you also sent another identifier, and that one is used. It is not an error, so that nobody can work out who is in your community by trying names.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestTaskNoMemberResponse" }, "examples": { "noMember": { "summary": "No member found", "value": { "success": true, "matched": 0, "data": { "matched": 0, "completed": [], "sentForReview": [] } } } } } } }, "400": { "description": "The request was rejected and no changes were made. The checks run in this order: the task key, who did it, that the evidence is a string, a null character in the evidence, half of a character pair in the evidence, a null character in the identifier the member is looked up by, `playerId` and its `platform`, the idempotency key, then whether the platform is known. A message names the spelling you sent.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badTaskKey": { "summary": "Task key missing, not a string or the wrong shape", "value": { "error": "taskKey is required (4–64 letters, digits, _ or -)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "taskKey" } }, "badOlderTaskKey": { "summary": "The same, when the deprecated alias was sent", "value": { "error": "task_key is required (4–64 letters, digits, _ or -)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "task_key" } }, "noMember": { "summary": "Nobody named", "value": { "error": "Send one of discordId, playerId with platform, xHandle, wallet, github or twitch to say who did it", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badEvidence": { "summary": "evidence is not a string", "value": { "error": "evidence must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "evidence" } }, "nullInEvidence": { "summary": "A null character in the evidence", "value": { "error": "evidence cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "evidence" } }, "halfPairInEvidence": { "summary": "An unpaired surrogate in the evidence", "value": { "error": "evidence must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "evidence" } }, "nullInIdentifier": { "summary": "A null character in the identifier the member is looked up by. The message names the field", "value": { "error": "xHandle cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "xHandle" } }, "badPlayerId": { "summary": "playerId not a string, or empty once trimmed", "value": { "error": "playerId must be a string of 1 to 255 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "longPlayerId": { "summary": "playerId over 255 characters", "value": { "error": "playerId cannot exceed 255 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "nullInPlayerId": { "summary": "A null character in playerId", "value": { "error": "playerId cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "noPlatform": { "summary": "playerId without a platform", "value": { "error": "platform is required with playerId", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "longPlatform": { "summary": "Platform over 50 characters", "value": { "error": "platform cannot exceed 50 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "nullInPlatform": { "summary": "A null character in the platform", "value": { "error": "platform cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "badPlatform": { "summary": "A platform with other characters", "value": { "error": "platform can only contain letters, digits and underscores", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "unknownPlatform": { "summary": "A platform that is not known", "value": { "error": "Unknown platform. Add it as a custom platform under Settings, Developers, Platforms, then send the task again", "code": "unknown_platform", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not have `quests:complete` (`insufficient_scope`: the body lists what was needed and what the key has, and the request still counts toward the key's rate limit). Or the member is named by a `playerId` on a `platform` that is a game's name, and the key is limited to other games of the community (`game_not_allowed`): nobody is looked up and nothing is completed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without the scope", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "quests:complete" ], "granted": [ "xp:grant", "xp:read" ] } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "The member is named by an account, and this instance does not support account linking yet (`not_available`, with `feature: \"linking\"`). No changes were made.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAvailableErrorResponse" }, "examples": { "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "linking" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflictUnknown" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "CEEJAY's bot, which completes quests, could not be reached or rejected the request (`bot_unavailable`: no changes were made, and the idempotency key is released), or did not respond within 12 seconds, or its response was lost: it failed part way, or the connection to it dropped (`bot_timeout`: the task may or may not have been completed, and the idempotency key stays reserved). After a `bot_timeout`, sending the task again is safe for a quest a member can complete once; a repeatable quest can be completed a second time. With an `idempotencyKey` the task is never sent to the bot twice.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unreachable": { "summary": "The bot could not be reached, or rejected: no changes were made", "value": { "error": "The quest engine could not be reached", "code": "bot_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "timeout": { "summary": "No answer in time", "value": { "error": "The quest engine did not answer in time, so the task may or may not have been completed", "code": "bot_timeout", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "answerLost": { "summary": "The bot's answer was lost: it failed part way, or the connection dropped", "value": { "error": "The quest engine did not give an answer, so the task may or may not have been completed", "code": "bot_timeout", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "description": "Discord could not be asked, and no changes were made: retry the request shortly. Either CEEJAY has no profile for the `discordId` and could not check with Discord whether it is a member of your server, or a matching quest requires a role and the member's roles could not be read. Both carry the code `discord_unavailable`. Or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "discordUnavailable": { "summary": "Discord could not be asked", "value": { "error": "Could not check with Discord that this ID is a member of the server, so nothing was changed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "rolesUnavailable": { "summary": "The member's roles could not be read", "value": { "error": "Could not read this member's roles from Discord, so no quest was completed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/quests/external/complete": { "servers": [ { "url": "https://ceejay.communitystudios.xyz/api", "description": "The shared CEEJAY service. This operation is not under /api/v1: its full URL is https://ceejay.communitystudios.xyz/api/quests/external/complete." }, { "url": "https://{dashboardHost}/api", "description": "A dedicated CEEJAY instance: your dashboard's URL followed by /api. This operation is not under /api/v1.", "variables": { "dashboardHost": { "default": "dashboard.example.com", "description": "The domain you see in your browser when you open your dashboard, without https://." } } } ], "post": { "tags": [ "Quests" ], "summary": "Complete a quest task (legacy endpoint)", "description": "The legacy endpoint of Complete a quest task. It still works, takes the same body and returns the same response as `POST /quests/tasks/complete`. New code should use that one. This endpoint is at the dashboard's URL followed by `/api/quests/external/complete`, with no `/v1`, so it lists its own servers.\n\nTells CEEJAY that a member did something your own platform checks. CEEJAY completes the quest task of the type Completed by your API that has your `taskKey`. When that was the quest's last task, it completes the quest and grants its rewards.\n\n**Required scope:** `quests:complete` (a key with the `*` scope can also call it).\n\n**Who.** Send one of `discordId`, `playerId` with `platform`, `xHandle`, `wallet`, `github` and `twitch`. With more than one, CEEJAY uses the first in that order. A `discordId` that is `null` or an empty string is skipped, and the next one is used. A `discordId` CEEJAY has a member profile for is used as it is. One it has no profile for is looked up in Discord first: an ID that is not a member of your server returns `202` with `matched: 0`, like any identifier that does not match a member, and when the Discord API is unavailable the call returns `503` with the code `discord_unavailable` and nothing happens. `playerId` is the member's ID in your game on `platform`, as you linked it with `POST /members/link`; a platform your community does not know returns `400` with the code `unknown_platform`. The others are strings, or whole numbers that are read as their digits, and must match an account the member connected in your community, which you can also set with `POST /members/link` under the platform `twitter`, `metamask`, `github` or `twitch`. When CEEJAY finds no member it returns `202` with `matched: 0`, not an error, and says nothing else about the member, so that nobody can work out who is in your community by trying names.\n\n**What it does.** CEEJAY completes every task of that type whose key is your `taskKey`, in every quest on your server that is active and inside its dates, applying the quest's own rules: the role it requires, the member's level and season XP, program, prerequisite quest, the wait between runs, the per-member and overall limits and the community's daily quest limit. A quest whose key does not match is never started. A quest that requires a role is completed only for a member who has it; a member who already has a run of that quest open is not checked again. When a rule blocks a quest, the call still returns `200` with that quest omitted. CEEJAY does not check that what you report is true, or that a key belongs to one task only: a key shared by several tasks completes all of them. When the last task of a quest is done, the quest completes and grants XP, coins, the badge, the role and any extra rewards set on it in the Rewards Engine, and `quest.completed` is sent to your webhooks.\n\nWhen a matching quest requires a role and CEEJAY's bot cannot read the member's roles from Discord, nothing is started or completed and the call returns `503` with the code `discord_unavailable`: retry shortly.\n\n**Review.** If the task's own review switch is on, or you send `review: true`, nothing completes yet. The report waits in the Review Queue, with `evidence` as the proof, until a moderator approves or rejects it, and the quest is listed in `data.sentForReview`. While it is awaiting review, the quest's other automatic tasks do not advance for that member.\n\n**The body.** A body that is not a JSON object is read as an empty one, so it returns the `taskKey` message.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. A key is stored only when the call changed something: a `200` in which at least one quest was completed or sent for review. A retry then returns the original response, with `data.duplicate: true` and the header `Idempotent-Replayed: true`. A `202` and a `200` with both lists empty store no key, so a retry with the same key is processed as a new request, for example after the player has linked the account. When CEEJAY's bot does not respond in time (`502` with the code `bot_timeout`), the task may or may not have been completed. Sending it again without a key is safe for a quest a member can complete once, and can complete a repeatable quest a second time. With a key it is never sent to the bot twice: the same key returns `409` with the code `idempotency_in_progress` for a minute, and `idempotency_outcome_unknown` after that. Each key is tied to one request payload: the same key on another operation, or with other values, returns `409` with the code `idempotency_key_reused`. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable`. A body that sends `idempotency_key` gets no key: this operation never read that spelling.", "operationId": "completeQuestTaskLegacy", "x-required-scope": [ "quests:complete" ], "x-since": "1.0.0", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestTaskRequest" }, "examples": { "byDiscordId": { "summary": "Name the member by Discord ID, with a link as evidence", "value": { "taskKey": "tk_4k2m9x7qzb", "discordId": "409876543210987654", "evidence": "https://acme.example/players/nova/tutorial", "idempotencyKey": "tutorial-88213004" } }, "byPlayerId": { "summary": "Name the member by their ID in your game", "value": { "taskKey": "tk_4k2m9x7qzb", "playerId": "88213004", "platform": "roblox" } }, "byXHandle": { "summary": "Name the member by the X account they connected", "value": { "taskKey": "tk_4k2m9x7qzb", "xHandle": "@novaplays" } }, "forReview": { "summary": "Ask for a moderator to look at it first", "value": { "taskKey": "tk_7d3p1w8hfa", "github": "novaplays", "evidence": "https://github.com/acme/game/pull/128", "review": true } } } } } }, "responses": { "200": { "description": "The report reached CEEJAY's bot, which completes quests. `data.completed` lists the quests this call finished and `data.sentForReview` the ones whose task went to review. Both are empty when the task was completed but the quest has more tasks, when a rule stopped the completion and when no task had the key: the call does not say which.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestTaskResponse" }, "examples": { "finishedQuest": { "summary": "The task was the last one, so the quest completed", "value": { "success": true, "matched": 1, "completed": [ { "questId": 42, "title": "Finish the Acme tutorial" } ], "data": { "matched": 1, "completed": [ { "questId": 42, "questTitle": "Finish the Acme tutorial" } ], "sentForReview": [], "duplicate": false } } }, "sentForReview": { "summary": "The report went to the Review Queue", "value": { "success": true, "matched": 1, "completed": [], "data": { "matched": 1, "completed": [], "sentForReview": [ { "questId": 57, "questTitle": "Merge a pull request" } ], "duplicate": false } } }, "noQuestFinished": { "summary": "No quest finished by this call", "value": { "success": true, "matched": 1, "completed": [], "data": { "matched": 1, "completed": [], "sentForReview": [], "duplicate": false } } } } } } }, "202": { "description": "CEEJAY found no member for the identifier. No changes were made, and no idempotency key is stored. A `discordId` that is not a string of 17 to 20 digits returns this too (a JSON number is never converted to a string), and so does an identifier that is empty or `null`, or that is neither a string nor a whole number up to 9007199254740991. A `discordId` CEEJAY has no member profile for that is not a member of your server in Discord returns it as well. One exception: a `discordId` that is `null` or empty is skipped when you also sent another identifier, and that one is used. It is not an error, so that nobody can work out who is in your community by trying names.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteQuestTaskNoMemberResponse" }, "examples": { "noMember": { "summary": "No member found", "value": { "success": true, "matched": 0, "data": { "matched": 0, "completed": [], "sentForReview": [] } } } } } } }, "400": { "description": "The request was rejected and no changes were made. The checks run in this order: the task key, who did it, that the evidence is a string, a null character in the evidence, half of a character pair in the evidence, a null character in the identifier the member is looked up by, `playerId` and its `platform`, the idempotency key, then whether the platform is known. A message names the spelling you sent.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badTaskKey": { "summary": "Task key missing, not a string or the wrong shape", "value": { "error": "taskKey is required (4–64 letters, digits, _ or -)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "taskKey" } }, "badOlderTaskKey": { "summary": "The same, when the deprecated alias was sent", "value": { "error": "task_key is required (4–64 letters, digits, _ or -)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "task_key" } }, "noMember": { "summary": "Nobody named", "value": { "error": "Send one of discordId, playerId with platform, xHandle, wallet, github or twitch to say who did it", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badEvidence": { "summary": "evidence is not a string", "value": { "error": "evidence must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "evidence" } }, "nullInEvidence": { "summary": "A null character in the evidence", "value": { "error": "evidence cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "evidence" } }, "halfPairInEvidence": { "summary": "An unpaired surrogate in the evidence", "value": { "error": "evidence must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "evidence" } }, "nullInIdentifier": { "summary": "A null character in the identifier the member is looked up by. The message names the field", "value": { "error": "xHandle cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "xHandle" } }, "badPlayerId": { "summary": "playerId not a string, or empty once trimmed", "value": { "error": "playerId must be a string of 1 to 255 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "longPlayerId": { "summary": "playerId over 255 characters", "value": { "error": "playerId cannot exceed 255 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "nullInPlayerId": { "summary": "A null character in playerId", "value": { "error": "playerId cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerId" } }, "noPlatform": { "summary": "playerId without a platform", "value": { "error": "platform is required with playerId", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "longPlatform": { "summary": "Platform over 50 characters", "value": { "error": "platform cannot exceed 50 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "nullInPlatform": { "summary": "A null character in the platform", "value": { "error": "platform cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "badPlatform": { "summary": "A platform with other characters", "value": { "error": "platform can only contain letters, digits and underscores", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "platform" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "unknownPlatform": { "summary": "A platform that is not known", "value": { "error": "Unknown platform. Add it as a custom platform under Settings, Developers, Platforms, then send the task again", "code": "unknown_platform", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "The member is named by an account, and this instance does not support account linking yet (`not_available`, with `feature: \"linking\"`). No changes were made.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAvailableErrorResponse" }, "examples": { "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "linking" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflictUnknown" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "CEEJAY's bot, which completes quests, could not be reached or rejected the request (`bot_unavailable`: no changes were made, and the idempotency key is released), or did not respond within 12 seconds, or its response was lost: it failed part way, or the connection to it dropped (`bot_timeout`: the task may or may not have been completed, and the idempotency key stays reserved). After a `bot_timeout`, sending the task again is safe for a quest a member can complete once; a repeatable quest can be completed a second time. With an `idempotencyKey` the task is never sent to the bot twice.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unreachable": { "summary": "The bot could not be reached, or rejected: no changes were made", "value": { "error": "The quest engine could not be reached", "code": "bot_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "timeout": { "summary": "No answer in time", "value": { "error": "The quest engine did not answer in time, so the task may or may not have been completed", "code": "bot_timeout", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "answerLost": { "summary": "The bot's answer was lost: it failed part way, or the connection dropped", "value": { "error": "The quest engine did not give an answer, so the task may or may not have been completed", "code": "bot_timeout", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "description": "Discord could not be asked, and no changes were made: retry the request shortly. Either CEEJAY has no profile for the `discordId` and could not check with Discord whether it is a member of your server, or a matching quest requires a role and the member's roles could not be read. Both carry the code `discord_unavailable`. Or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "discordUnavailable": { "summary": "Discord could not be asked", "value": { "error": "Could not check with Discord that this ID is a member of the server, so nothing was changed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "rolesUnavailable": { "summary": "The member's roles could not be read", "value": { "error": "Could not read this member's roles from Discord, so no quest was completed", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/roles": { "get": { "tags": [ "Roles" ], "summary": "List roles", "description": "Lists your server's roles, highest first, without `@everyone`, and says for each whether a key may grant and revoke it through Grant a role and Revoke a role.\n\n**Required scope:** `roles:manage` (a key with the `*` scope can also call it).\n\nUse it to find a `roleId`, and to see beforehand which roles the API rejects. `grantable` is decided by the same checks the two role operations make. `can_mention_everyone` is reported only where your server's `@everyone` role cannot mention everyone itself. `above_bot` is reported when CEEJAY could read the bot's own highest role and the role is at or above it; when that could not be read it is never reported, and Discord may still reject such a role.\n\nThe whole list is returned in one response (Discord allows 250 roles), so `page.nextCursor` is always `null`. CEEJAY reads the list from Discord and caches it for up to a minute. A role is never reported as grantable when your community's bot master roles could not be read: the call then returns `503`.\n\nNever returned: a role's permissions, which members have it, or the tags of a managed role.", "operationId": "listRoles", "x-required-scope": [ "roles:manage" ], "x-since": "1.0.0", "responses": { "200": { "description": "The roles.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRolesResponse" }, "examples": { "roles": { "summary": "Three roles", "value": { "success": true, "data": [ { "roleId": "982371004827100301", "name": "Moderator", "color": 15158332, "position": 12, "managed": false, "grantable": false, "notGrantableReason": "can_moderate" }, { "roleId": "982371004827100394", "name": "Tournament winner", "color": 15844367, "position": 5, "managed": false, "grantable": true, "notGrantableReason": null }, { "roleId": "982371004827100377", "name": "Server Booster", "color": 16023551, "position": 4, "managed": true, "grantable": false, "notGrantableReason": "managed" } ], "page": { "nextCursor": null, "limit": 3 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "description": "The key has used up its requests for this minute (`rate_limited`), or Discord is rate limiting the bot for the role list (`discord_rate_limited`, with `retryAfter` and `Retry-After` when Discord gave a wait).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "limited": { "summary": "Too many requests", "value": { "error": "Rate limit exceeded", "code": "rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 34 } }, "discordLimited": { "summary": "Discord rate limit, with the wait Discord requested", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 3 } }, "discordLimitedNoWait": { "summary": "Discord rate limit, with no wait given", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "500": { "description": "Something failed on CEEJAY's side (`internal_error`), or this instance has no connection to Discord (`discord_not_configured`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "failed": { "summary": "Server error", "value": { "error": "Internal server error", "code": "internal_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noBot": { "summary": "This instance has no connection to Discord", "value": { "error": "This instance cannot reach Discord yet", "code": "discord_not_configured", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "description": "The list could not be put together, so nothing is listed. Either the server's roles could not be read from Discord (`roles_unavailable`), or CEEJAY could not read which roles are your community's bot master roles (`dashboard_roles_unavailable`). Retry with backoff.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noRoleList": { "summary": "The role list could not be read", "value": { "error": "Could not read this server's roles from Discord", "code": "roles_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noDashboardRoles": { "summary": "The bot master roles could not be read", "value": { "error": "Could not read which roles give access to the CEEJAY dashboard, so no role is listed", "code": "dashboard_roles_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/roles/grant": { "post": { "tags": [ "Roles" ], "summary": "Grant a role", "description": "Grants a member a Discord role. A member who already has it is not an error.\n\n**Required scope:** `roles:manage` (a key with the `*` scope can also call it).\n\nOnly an ordinary role of your own server can be granted. Before anything is changed CEEJAY looks the role up in your server's role list, and rejects it with `403` and the code `role_not_allowed` when it is the `@everyone` role, a role that Discord or another app manages (a bot's own role, the server booster role), a role that can moderate or manage the server (one with Administrator, Kick Members, Ban Members, Timeout Members, Manage Server, Manage Channels, Manage Roles, View Audit Log, Manage Messages, Manage Nicknames, Manage Webhooks, Manage Expressions, Manage Events, Manage Threads, Mute Members, Deafen Members or Move Members), or a role that can mention `@everyone`, `@here` and all roles. That last check is made only where your server's own `@everyone` role cannot: where it can, every member already has the permission, a role that also has it adds nothing, and it is not rejected. A role that moderates only through the permission overrides of a channel cannot be seen from the role list. A role that is not in your server returns `404` with the code `role_not_found`. List roles (`GET /roles`) says for every role whether a key may change it, and why not.\n\nA bot master role is rejected as well, with `403` and the code `role_not_allowed`. That is a role your community added under **Settings → General → Team Management**, as one of its **Additional Bot Master Roles**: anyone with this role has full access to the CEEJAY dashboard, whatever its Discord permissions are. CEEJAY reads that list on every call. When it cannot be read the call returns `503` with the code `dashboard_roles_unavailable` and nothing is changed.\n\nCEEJAY reads the role list from Discord and caches it for up to a minute, so a change to a role's permissions can take up to a minute to apply. When the list cannot be read the call returns `503` with the code `roles_unavailable` and nothing is changed.\n\nThe CEEJAY bot needs **Manage Roles**, and its own role must be higher than the role you are granting in **Server Settings → Roles**. Otherwise Discord rejects and the call returns `403` with the code `bot_missing_permission`.\n\nThe change shows in your server's audit log in Discord, made by the CEEJAY bot, with the reason `API key: ` followed by the name of the key that made the call.\n\nDiscord's own rate limit can also return `429`, with the code `discord_rate_limited`. `retryAfter` and the `Retry-After` header contain the wait Discord requested, in whole seconds, if it gave one. Do not retry in a tight loop.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member and role. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is changed. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing. A second change of the same role has the same effect on Discord, so when a first request was started more than a minute ago and never finished, a retry with the same key makes the change again and returns normally.", "operationId": "grantRole", "x-required-scope": [ "roles:manage" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleChangeRequest" }, "examples": { "change": { "summary": "Grant a role", "value": { "discordId": "409876543210987654", "roleId": "982371004827100394" } } } } } }, "responses": { "200": { "description": "The role was granted. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRoleResponse" }, "examples": { "done": { "summary": "Grant a role", "value": { "success": true, "data": { "discordId": "409876543210987654", "roleId": "982371004827100394", "action": "granted", "duplicate": false } } } } } } }, "400": { "description": "The request was rejected, either by CEEJAY (the body, Discord ID, role ID, then the idempotency key) or by Discord (the last example, with the code `discord_error`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badRole": { "summary": "Invalid role ID", "value": { "error": "roleId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "roleId" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "discordRefused": { "summary": "Discord rejected the change", "value": { "error": "Discord API error: 400", "code": "discord_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "details": "{\"message\": \"Invalid Form Body\", \"code\": 50035}" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key lacks the scope (`insufficient_scope`), the bot cannot manage this role (`bot_missing_permission`), or the role is one the API never changes (`role_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScopeErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "missingScope": { "summary": "Key without the scope", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "roles:manage" ], "granted": [ "xp:read" ] } }, "botCannotManage": { "summary": "The bot lacks permission", "value": { "error": "Bot lacks permission to manage this role", "code": "bot_missing_permission", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "canModerate": { "summary": "A role that can moderate or manage the server", "value": { "error": "Roles that can moderate or manage the server cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "canMentionEveryone": { "summary": "A role that can mention everyone, in a server whose @everyone role cannot", "value": { "error": "Roles that can mention everyone cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "managedRole": { "summary": "A role Discord or another app manages", "value": { "error": "Roles managed by Discord or by another app cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "everyoneRole": { "summary": "The @everyone role", "value": { "error": "The @everyone role cannot be given or removed", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "dashboardRole": { "summary": "A bot master role, which gives access to the CEEJAY dashboard", "value": { "error": "Roles that give access to the CEEJAY dashboard cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "The role is not one of your server's (`role_not_found`), or Discord found no such member in your server (`member_not_found`: the role was found a moment before, so it is the member who is not there). A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "roleNotFound": { "summary": "Role not in your server", "value": { "error": "Role not found in this server", "code": "role_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "missing": { "summary": "Member not in your server", "value": { "error": "Member or role not found in this server", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "The key has used up its requests for this minute (`rate_limited`), or Discord is rate limiting the bot, for the role list or for the change itself (`discord_rate_limited`). For Discord's limit, `retryAfter` and `Retry-After` contain the wait Discord requested, if it gave one, and `X-RateLimit-Remaining` is not `0` unless the key's own window is used up too.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "limited": { "summary": "Too many requests", "value": { "error": "Rate limit exceeded", "code": "rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 34 } }, "discordLimited": { "summary": "Discord rate limit, with the wait Discord requested", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 3 } }, "discordLimitedNoWait": { "summary": "Discord rate limit, with no wait given", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "500": { "description": "Something failed on CEEJAY's side (`internal_error`), or this instance has no connection to Discord (`discord_not_configured`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "failed": { "summary": "Server error", "value": { "error": "Internal server error", "code": "internal_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noBot": { "summary": "This instance has no connection to Discord", "value": { "error": "This instance cannot reach Discord yet", "code": "discord_not_configured", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "description": "A check CEEJAY makes before it changes a role could not be made, and nothing was changed. Either it could not read your server's role list from Discord (`roles_unavailable`), or it could not read whether the role is one of your community's bot master roles (`dashboard_roles_unavailable`). Retry with backoff. Or Discord did not answer the change itself within 10 seconds (`discord_unavailable`): the change may or may not have been made, the idempotency key stays reserved and the request is safe to repeat. Or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noRoleList": { "summary": "The role list could not be read", "value": { "error": "Could not read this server's roles from Discord, so nothing was changed", "code": "roles_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noDashboardCheck": { "summary": "The bot master roles could not be read", "value": { "error": "Could not check whether this role gives access to the CEEJAY dashboard, so nothing was changed", "code": "dashboard_roles_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "changeTimedOut": { "summary": "The change timed out", "value": { "error": "Discord did not answer in time, so the role may or may not have been given", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "default": { "description": "Any other status Discord returns is passed on, with the code `discord_error`. `error` is `Discord API error: ` and `details` is Discord's reply. After a `5xx` from Discord the change may or may not have been made.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordErrorResponse" }, "examples": { "discord": { "summary": "Discord is unavailable", "value": { "error": "Discord API error: 503", "code": "discord_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "details": "{\"message\": \"Service Unavailable\"}" } } } } } } } } }, "/roles/revoke": { "post": { "tags": [ "Roles" ], "summary": "Revoke a role", "description": "Takes a Discord role away from a member. A member who does not have it is not an error.\n\n**Required scope:** `roles:manage` (a key with the `*` scope can also call it).\n\nOnly an ordinary role of your own server can be revoked. Before anything is changed CEEJAY looks the role up in your server's role list, and rejects it with `403` and the code `role_not_allowed` when it is the `@everyone` role, a role that Discord or another app manages (a bot's own role, the server booster role), a role that can moderate or manage the server (one with Administrator, Kick Members, Ban Members, Timeout Members, Manage Server, Manage Channels, Manage Roles, View Audit Log, Manage Messages, Manage Nicknames, Manage Webhooks, Manage Expressions, Manage Events, Manage Threads, Mute Members, Deafen Members or Move Members), or a role that can mention `@everyone`, `@here` and all roles. That last check is made only where your server's own `@everyone` role cannot: where it can, every member already has the permission, a role that also has it adds nothing, and it is not rejected. A role that moderates only through the permission overrides of a channel cannot be seen from the role list. A role that is not in your server returns `404` with the code `role_not_found`. List roles (`GET /roles`) says for every role whether a key may change it, and why not.\n\nA bot master role is rejected as well, with `403` and the code `role_not_allowed`. That is a role your community added under **Settings → General → Team Management**, as one of its **Additional Bot Master Roles**: anyone with this role has full access to the CEEJAY dashboard, whatever its Discord permissions are. CEEJAY reads that list on every call. When it cannot be read the call returns `503` with the code `dashboard_roles_unavailable` and nothing is changed.\n\nCEEJAY reads the role list from Discord and caches it for up to a minute, so a change to a role's permissions can take up to a minute to apply. When the list cannot be read the call returns `503` with the code `roles_unavailable` and nothing is changed.\n\nThe CEEJAY bot needs **Manage Roles**, and its own role must be higher than the role you are revoking in **Server Settings → Roles**. Otherwise Discord rejects and the call returns `403` with the code `bot_missing_permission`.\n\nThe change shows in your server's audit log in Discord, made by the CEEJAY bot, with the reason `API key: ` followed by the name of the key that made the call.\n\nDiscord's own rate limit can also return `429`, with the code `discord_rate_limited`. `retryAfter` and the `Retry-After` header contain the wait Discord requested, in whole seconds, if it gave one. Do not retry in a tight loop.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same member and role. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is changed. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing. A second change of the same role has the same effect on Discord, so when a first request was started more than a minute ago and never finished, a retry with the same key makes the change again and returns normally.", "operationId": "revokeRole", "x-required-scope": [ "roles:manage" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleChangeRequest" }, "examples": { "change": { "summary": "Revoke a role", "value": { "discordId": "409876543210987654", "roleId": "982371004827100394" } } } } } }, "responses": { "200": { "description": "The role was revoked. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeRoleResponse" }, "examples": { "done": { "summary": "Revoke a role", "value": { "success": true, "data": { "discordId": "409876543210987654", "roleId": "982371004827100394", "action": "revoked", "duplicate": false } } } } } } }, "400": { "description": "The request was rejected, either by CEEJAY (the body, Discord ID, role ID, then the idempotency key) or by Discord (the last example, with the code `discord_error`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badId": { "summary": "Invalid Discord ID", "value": { "error": "discordId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "discordId" } }, "badRole": { "summary": "Invalid role ID", "value": { "error": "roleId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "roleId" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "discordRefused": { "summary": "Discord rejected the change", "value": { "error": "Discord API error: 400", "code": "discord_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "details": "{\"message\": \"Invalid Form Body\", \"code\": 50035}" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key lacks the scope (`insufficient_scope`), the bot cannot manage this role (`bot_missing_permission`), or the role is one the API never changes (`role_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScopeErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "missingScope": { "summary": "Key without the scope", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "roles:manage" ], "granted": [ "xp:read" ] } }, "botCannotManage": { "summary": "The bot lacks permission", "value": { "error": "Bot lacks permission to manage this role", "code": "bot_missing_permission", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "canModerate": { "summary": "A role that can moderate or manage the server", "value": { "error": "Roles that can moderate or manage the server cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "canMentionEveryone": { "summary": "A role that can mention everyone, in a server whose @everyone role cannot", "value": { "error": "Roles that can mention everyone cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "managedRole": { "summary": "A role Discord or another app manages", "value": { "error": "Roles managed by Discord or by another app cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "everyoneRole": { "summary": "The @everyone role", "value": { "error": "The @everyone role cannot be given or removed", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "dashboardRole": { "summary": "A bot master role, which gives access to the CEEJAY dashboard", "value": { "error": "Roles that give access to the CEEJAY dashboard cannot be given or removed through the API", "code": "role_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "The role is not one of your server's (`role_not_found`), or Discord found no such member in your server (`member_not_found`: the role was found a moment before, so it is the member who is not there). A member who has only just joined can take up to 15 seconds to be found. Wait 15 seconds before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "roleNotFound": { "summary": "Role not in your server", "value": { "error": "Role not found in this server", "code": "role_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "missing": { "summary": "Member not in your server", "value": { "error": "Member or role not found in this server", "code": "member_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "The key has used up its requests for this minute (`rate_limited`), or Discord is rate limiting the bot, for the role list or for the change itself (`discord_rate_limited`). For Discord's limit, `retryAfter` and `Retry-After` contain the wait Discord requested, if it gave one, and `X-RateLimit-Remaining` is not `0` unless the key's own window is used up too.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "limited": { "summary": "Too many requests", "value": { "error": "Rate limit exceeded", "code": "rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 34 } }, "discordLimited": { "summary": "Discord rate limit, with the wait Discord requested", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 3 } }, "discordLimitedNoWait": { "summary": "Discord rate limit, with no wait given", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "500": { "description": "Something failed on CEEJAY's side (`internal_error`), or this instance has no connection to Discord (`discord_not_configured`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "failed": { "summary": "Server error", "value": { "error": "Internal server error", "code": "internal_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noBot": { "summary": "This instance has no connection to Discord", "value": { "error": "This instance cannot reach Discord yet", "code": "discord_not_configured", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "description": "A check CEEJAY makes before it changes a role could not be made, and nothing was changed. Either it could not read your server's role list from Discord (`roles_unavailable`), or it could not read whether the role is one of your community's bot master roles (`dashboard_roles_unavailable`). Retry with backoff. Or Discord did not answer the change itself within 10 seconds (`discord_unavailable`): the change may or may not have been made, the idempotency key stays reserved and the request is safe to repeat. Or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noRoleList": { "summary": "The role list could not be read", "value": { "error": "Could not read this server's roles from Discord, so nothing was changed", "code": "roles_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noDashboardCheck": { "summary": "The bot master roles could not be read", "value": { "error": "Could not check whether this role gives access to the CEEJAY dashboard, so nothing was changed", "code": "dashboard_roles_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "changeTimedOut": { "summary": "The change timed out", "value": { "error": "Discord did not answer in time, so the role may or may not have been taken away", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "default": { "description": "Any other status Discord returns is passed on, with the code `discord_error`. `error` is `Discord API error: ` and `details` is Discord's reply. After a `5xx` from Discord the change may or may not have been made.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordErrorResponse" }, "examples": { "discord": { "summary": "Discord is unavailable", "value": { "error": "Discord API error: 503", "code": "discord_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "details": "{\"message\": \"Service Unavailable\"}" } } } } } } } } }, "/channels": { "get": { "tags": [ "Channels" ], "summary": "List channels", "description": "Lists your server's text, announcement and forum channels and its categories, in Discord's order, so you can find the `channelId` Send a message needs.\n\n**Required scope:** `messages:send` (a key with the `*` scope can also call it).\n\n`sendable` is `true` for the kinds of channel Send a message can post to. Whether the bot has permission in a given channel cannot be told from the list. `private` marks a channel that is hidden from `@everyone`.\n\nThe whole list is returned in one response (Discord allows 500 channels), so `page.nextCursor` is always `null`. CEEJAY reads the list from Discord and caches it for up to a minute. A failed read is an error, never an empty list.\n\nNever returned: topics, permission settings, last message IDs, the age-restricted flag, slow-mode settings or members.", "operationId": "listChannels", "x-required-scope": [ "messages:send" ], "x-since": "1.0.0", "responses": { "200": { "description": "The channels.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChannelsResponse" }, "examples": { "channels": { "summary": "A category and two channels", "value": { "success": true, "data": [ { "channelId": "718230049827100300", "name": "Community", "type": "category", "parentId": null, "position": 0, "private": false, "sendable": false }, { "channelId": "718230049827100384", "name": "announcements", "type": "announcement", "parentId": "718230049827100300", "position": 0, "private": false, "sendable": true }, { "channelId": "718230049827100391", "name": "game-log", "type": "text", "parentId": "718230049827100300", "position": 1, "private": true, "sendable": true } ], "page": { "nextCursor": null, "limit": 3 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "description": "The key has used up its requests for this minute (`rate_limited`), or Discord is rate limiting the bot for the channel list (`discord_rate_limited`, with `retryAfter` and `Retry-After` when Discord gave a wait).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "limited": { "summary": "Too many requests", "value": { "error": "Rate limit exceeded", "code": "rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 34 } }, "discordLimited": { "summary": "Discord rate limit, with the wait Discord gave", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 3 } }, "discordLimitedNoWait": { "summary": "Discord rate limit, with no wait given", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "500": { "description": "Something failed on CEEJAY's side (`internal_error`), or this instance has no connection to Discord (`discord_not_configured`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "failed": { "summary": "Server error", "value": { "error": "Internal server error", "code": "internal_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noBot": { "summary": "This instance has no connection to Discord", "value": { "error": "This instance cannot reach Discord yet", "code": "discord_not_configured", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "description": "The server's channels could not be read from Discord, so nothing is listed. Retry with backoff.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noChannelList": { "summary": "The channel list could not be read", "value": { "error": "Could not read this server's channels from Discord", "code": "channels_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } } } } }, "/messages/send": { "post": { "tags": [ "Messages" ], "summary": "Send a message", "description": "Posts a message, embeds or both to a channel in your Discord server, as the CEEJAY bot.\n\n**Required scope:** `messages:send` (a key with the `*` scope can also call it).\n\nThe channel must be in your server. A channel in another server gets the same `404` as one that does not exist. The bot needs **View Channel** and **Send Messages** in the channel, and **Embed Links** for embeds to show. List channels (`GET /channels`) gives you the IDs.\n\n**Mentions.** Every message is sent so that only member mentions (`<@id>`) notify people. A role mention (`<@&id>`) notifies the role only when you list that role in `allowedRoleIds`. `@everyone` and `@here` never notify anyone through the API, and your server's own ID, which is the ID of its `@everyone` role, is rejected in `allowedRoleIds`.\n\n`content` is cut at 2,000 characters and only the first 10 `embeds` are sent. Neither is rejected. `embeds` must be a list: with no `content`, a value that is not a list returns `400`; with `content`, it is left out and the text is posted. Embeds go to Discord unchanged, so Discord decides whether they are valid. When Discord rejects a message, the status is Discord's and the body includes the code `discord_error` and `details`.\n\nDiscord's own rate limit can also return `429`, with the code `discord_rate_limited`. `retryAfter` and the `Retry-After` header contain the wait Discord requested, in whole seconds, if it gave one. A limit Discord sets for one channel stops calls for that channel only. Do not retry in a tight loop.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the original response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same channel, text, embeds and `allowedRoleIds`, as they would be posted. Each key is tied to one request payload: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is posted. A key is scoped to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing. CEEJAY cannot undo a posted message, so it never posts twice with one key: when a first request was started more than a minute ago and never finished (a timeout, or a `5xx` from Discord), the same key returns `409` with the code `idempotency_outcome_unknown`. Look in the channel, then use a new key if the message has to be sent again. A rejection from Discord (any `4xx`) does not use up the key, so the same key can be reused.", "operationId": "sendMessage", "x-required-scope": [ "messages:send" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" }, "examples": { "text": { "summary": "A plain message", "value": { "channelId": "718230049827100384", "content": "Tournament results are in. Congratulations to everyone who played." } }, "embed": { "summary": "A message with an embed", "value": { "channelId": "718230049827100384", "content": "Tournament results are in.", "embeds": [ { "title": "Weekend tournament", "description": "Congratulations to everyone who played.", "color": 5793266 } ] } }, "roleMention": { "summary": "A message that pings one role", "value": { "channelId": "718230049827100384", "content": "Sign-ups are open, <@&718230049827100399>.", "allowedRoleIds": [ "718230049827100399" ] } }, "withKey": { "summary": "A message that is safe to retry", "value": { "channelId": "718230049827100384", "content": "Season 4 starts now.", "idempotencyKey": "season-4-start" } } } } } }, "responses": { "200": { "description": "The message was posted. With `duplicate: true` it is the response to an earlier call with the same `idempotencyKey`: nothing was posted this time.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" }, "examples": { "sent": { "summary": "Posted", "value": { "success": true, "data": { "messageId": "1178230049827100384", "channelId": "718230049827100384", "duplicate": false } } } } } } }, "400": { "description": "The request was rejected, either by CEEJAY or by Discord (the last example, with the code `discord_error`). CEEJAY checks in this order: the body, channel ID, that `content` is a string, that `content` and the embeds are valid Unicode text, content or embeds, that `embeds` is a list when there is no `content`, `allowedRoleIds`, the idempotency key, then, with a key, how deeply the embeds are nested.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badChannel": { "summary": "Invalid channel ID", "value": { "error": "channelId must be a valid Discord snowflake (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "channelId" } }, "badContent": { "summary": "content is not a string", "value": { "error": "content must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "content" } }, "badContentUnicode": { "summary": "content contains an unpaired surrogate", "value": { "error": "content must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "content" } }, "badEmbedsUnicode": { "summary": "The embeds contain an unpaired surrogate", "value": { "error": "embeds must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "embeds" } }, "nothingToSend": { "summary": "Neither content nor embeds", "value": { "error": "Either content or embeds is required", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "embedsNotList": { "summary": "No content, and embeds that are not a list", "value": { "error": "embeds must be a list", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "embeds" } }, "badRoles": { "summary": "allowedRoleIds is not a list of up to 20 role IDs, or contains your server's own ID", "value": { "error": "allowedRoleIds must be a list of up to 20 valid Discord snowflakes (17-20 digits)", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "allowedRoleIds" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "embedsTooDeep": { "summary": "With a key, embeds nested more than 32 levels deep", "value": { "error": "embeds is nested too deeply", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "embeds" } }, "discordRefused": { "summary": "Discord rejected the message", "value": { "error": "Discord API error: 400", "code": "discord_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "details": "{\"message\": \"Cannot send an empty message\", \"code\": 50006}" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key lacks the scope (`insufficient_scope`), or the bot cannot send messages in this channel (`bot_missing_permission`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScopeErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "missingScope": { "summary": "Key without the scope", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "messages:send" ], "granted": [ "xp:read" ] } }, "botCannotSend": { "summary": "The bot lacks permission", "value": { "error": "Bot lacks permission to send messages in this channel", "code": "bot_missing_permission", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "The channel does not exist, is in another server, or the bot cannot see it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noChannel": { "summary": "Channel not found", "value": { "error": "Channel not found or bot has no access", "code": "channel_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflictUnknown" }, "429": { "description": "The key has used up its requests for this minute (`rate_limited`), or Discord is rate limiting the bot for this channel (`discord_rate_limited`, with `retryAfter` and `Retry-After` when Discord gave a wait).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "limited": { "summary": "Too many requests", "value": { "error": "Rate limit exceeded", "code": "rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 34 } }, "discordLimited": { "summary": "Discord rate limit, with the wait Discord requested", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 3 } }, "discordLimitedNoWait": { "summary": "Discord rate limit, with no wait given", "value": { "error": "Discord API rate limited, try again later", "code": "discord_rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "500": { "description": "Something failed on CEEJAY's side (`internal_error`), or this instance has no connection to Discord (`discord_not_configured`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "failed": { "summary": "Server error", "value": { "error": "Internal server error", "code": "internal_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noBot": { "summary": "This instance has no connection to Discord", "value": { "error": "This instance cannot reach Discord yet", "code": "discord_not_configured", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "503": { "description": "Discord did not respond within 10 seconds (`discord_unavailable`). Either the channel check timed out and nothing was posted, or the post timed out and the message may or may not have been posted: the idempotency key stays reserved, so see Retrying safely before you send it again. Or you sent an `idempotencyKey` and this instance does not support idempotency keys yet (`idempotency_unavailable`): nothing was changed, and waiting does not change that response.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "lookupTimedOut": { "summary": "The channel could not be checked in time", "value": { "error": "Discord did not answer in time, so the channel could not be checked and nothing was posted", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "postTimedOut": { "summary": "The post timed out", "value": { "error": "Discord did not answer in time, so the message may or may not have been posted", "code": "discord_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "keysUnavailable": { "summary": "Keys cannot be stored yet", "value": { "error": "idempotencyKey cannot be used on this community yet, so nothing was changed", "code": "idempotency_unavailable", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "default": { "description": "Any other status Discord returns is passed on, with the code `discord_error`. `error` is `Discord API error: ` and `details` is Discord's reply. After a `5xx` from Discord the message may or may not have been posted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordErrorResponse" }, "examples": { "discord": { "summary": "Discord is unavailable", "value": { "error": "Discord API error: 503", "code": "discord_error", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "details": "{\"message\": \"Service Unavailable\"}" } } } } } } } } }, "/events/emit": { "post": { "tags": [ "Events" ], "summary": "Emit an event", "description": "Sends a custom event from your own system to the webhook subscriptions on your server that listen for it.\n\n**Required scope:** `events:emit` (a key with the `*` scope can also call it).\n\nThe event is delivered as `custom.`. A name that already starts with `custom.` is not given the prefix twice. A name contains 1 to 93 letters, digits, `.`, `_`, `:` or `-` after that prefix. Any other name is refused with `400`, and nothing is sent. A subscription receives it when it lists that exact name, `custom.event` (every custom event) or `*` (every event).\n\nEach delivery is the same signed request as any other webhook (see the `custom.event` webhook in this document), sent as attempt 1. One call creates one delivery ID: every subscription receives the same body and the same `X-CEEJAY-Delivery`. CEEJAY calls the subscriptions one after another, with up to 5 seconds for each, and responds when all have been attempted, so the call takes as long as the subscribers do. `results` says how each one went. A failed delivery is retried by CEEJAY, up to 4 more times, and a subscription that fails 10 times in a row is switched off. An event nobody listens for still succeeds, with `subscribersNotified` at `0`. Your `data` is passed on as you sent it: CEEJAY adds nothing to it.\n\n**Retries.** Send `idempotencyKey` to make a retry safe. When the same request is sent again with its key, nothing happens a second time: the response is the first response, with `duplicate: true` and the header `Idempotent-Replayed: true`. For this operation the same request is the same event name and data. One key is one request: two requests for one event need two keys, for example `match-9:coins` and `match-9:xp`. A key that was used for a different request returns `409` with the code `idempotency_key_reused`, and nothing is sent. A key belongs to the API key that sent it and is retained for 30 days. On an instance that does not support idempotency keys yet, a request that sends one returns `503` with the code `idempotency_unavailable` and changes nothing. A call is stored against its key once it returned `200`, also when some or all of its deliveries failed: CEEJAY retries those itself, so a repeat with the same key sends nothing. To send the event again, use a new key. A webhook cannot be recalled once sent, so when a first request was started more than a minute ago and never finished, the same key returns `409` with the code `idempotency_outcome_unknown`.", "operationId": "emitEvent", "x-required-scope": [ "events:emit" ], "x-since": "1.0.0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitEventRequest" }, "examples": { "purchase": { "summary": "A purchase on your own store", "value": { "event": "purchase.completed", "data": { "discordId": "409876543210987654", "sku": "season-pass", "value": 24.99 }, "idempotencyKey": "order-88213-event" } } } } } }, "responses": { "200": { "description": "The event was sent to every matching subscription. With `duplicate: true` it is the response to an earlier call that sent the same `idempotencyKey`: nothing was sent this time.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitEventResponse" }, "examples": { "delivered": { "summary": "Two subscribers", "value": { "success": true, "data": { "event": "custom.purchase.completed", "subscribersNotified": 2, "results": [ { "subscriptionId": 4, "name": "Ops relay", "status": "delivered", "httpStatus": 200 }, { "subscriptionId": 7, "name": "Data warehouse", "status": "failed", "httpStatus": 503, "error": "HTTP 503" } ], "duplicate": false } } }, "nobody": { "summary": "Nobody listening", "value": { "success": true, "data": { "event": "custom.purchase.completed", "subscribersNotified": 0, "results": [], "duplicate": false } } } } } } }, "400": { "description": "The request was refused and nothing was sent. The checks run in this order: the body, a missing name or one that is not text, a name over 100 characters, the characters of the name, a null character anywhere in `data`, `data` nested more than 32 levels deep, `data` that is not well-formed Unicode, then the idempotency key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "Body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "missing": { "summary": "No event name", "value": { "error": "event is required and must be a string", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "event" } }, "tooLong": { "summary": "Name over 100 characters", "value": { "error": "event name cannot exceed 100 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "event" } }, "badName": { "summary": "Name with a character that is not allowed, or over 93 characters after the prefix", "value": { "error": "event name must be 1-93 letters, digits, \".\", \"_\", \":\" or \"-\" (not counting a leading \"custom.\")", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "event" } }, "nullInData": { "summary": "A null character in data", "value": { "error": "data cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "data" } }, "dataTooDeep": { "summary": "data nested more than 32 levels deep", "value": { "error": "data is nested too deeply", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "data" } }, "dataBadUnicode": { "summary": "data that contains half of a surrogate pair", "value": { "error": "data must be valid Unicode text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "data" } }, "badKey": { "summary": "Invalid idempotency key", "value": { "error": "idempotencyKey must be a string of 1-128 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } }, "nullInKey": { "summary": "A null character in the idempotency key", "value": { "error": "idempotencyKey cannot contain a null character", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "idempotencyKey" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScopes" }, "404": { "description": "This instance has no webhook subscriptions yet (`not_available`, with `feature: \"events\"`). Nothing was sent.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAvailableErrorResponse" }, "examples": { "notAvailable": { "summary": "Not available on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "events" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/IdempotencyConflictUnknown" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/IdempotencyUnavailable" } } } }, "/games/{game}/connect/passes": { "post": { "tags": [ "Connect" ], "summary": "Create a connect pass", "description": "Creates a pass for one player your server has authenticated. The game sends it as `proof` when it starts a connect session, which is then at the verified level: CEEJAY trusts your server's verification of the player.\n\n**Required scope:** `players:connect`. A key with the `*` scope does not include it: tick **Act for a player** when you create the key.\n\nA pass lasts 10 minutes, works once, and only for this game and this `playerId`. Only its hash is stored, so it is returned once. When the pass carries a `playerName`, that name is what the member is shown.\n\nIt takes no `idempotencyKey`: creating a pass has no side effects, and a second call creates a second pass.\n\nA key that can create a pass can sign in any player who is already connected at the verified level, so keep `players:connect` on your own server.\n\n**Limit.** 600 requests a minute for the game, across the Connect operations, and not counted against the key's own number.", "operationId": "createConnectPass", "x-required-scope": [ "players:connect" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectPassRequest" }, "examples": { "request": { "summary": "A request", "value": { "playerId": "p_19", "playerName": "Nova77" } } } } } }, "responses": { "200": { "description": "The pass.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectPassResponse" }, "examples": { "pass": { "summary": "A pass", "value": { "success": true, "data": { "pass": "ceejay_pass_4f8a2c1e9b7d3e41f8a6b0c1d25f0c2a9b7d3e41f8a6b0c1d24f8a2c1e9b7d3e", "expiresAt": "2026-10-08T18:14:11.000Z" } } } } } } }, "400": { "description": "The request was rejected and no pass was created. The checks run in this order: the body, `playerId`, `playerName`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badPlayerId": { "summary": "A player ID outside the alphabet", "value": { "error": "playerId must be 1 to 128 characters: letters, digits and . _ : @ | + = -, starting with a letter or a digit", "code": "bad_player_id", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badName": { "summary": "A name that is not text, or is too long", "value": { "error": "playerName must be text of at most 80 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerName" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:connect` (`insufficient_scope`: the body adds `required` and `granted`, and a `*` key does not hold this scope), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "*" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/ConnectMethodNotAllowed" }, "409": { "description": "The game is paused or suspended (`game_paused`). No pass was created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "gamePaused": { "summary": "The game is paused", "value": { "error": "This game is paused", "code": "game_paused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/ConnectRateLimited" }, "500": { "$ref": "#/components/responses/ConnectInternalError" } } } }, "/games/{game}/connect/sessions": { "post": { "tags": [ "Connect" ], "summary": "Create a connect session", "description": "Starts a connect session for a player your server has authenticated, or attaches that player to a session a member started in Discord.\n\n**Required scope:** `players:connect`. A key with the `*` scope does not include it: tick **Act for a player** when you create the key.\n\nWithout `code`, the response includes a link (`url`), a code and the URL of a QR image: pass one of them to the player, who approves with their Discord account on CEEJAY's connect page. The session lasts 10 minutes and ends every earlier open session for the same player.\n\nWith `code`, no new session is created: the player is attached to the session of the member who created that code in Discord, the code is cleared, and `member` identifies whose code it was. Show that name to the player before the game approves.\n\n**Two confirmations.** A connection is saved only after the Discord member and the game have both confirmed. The game's confirmation comes from the game (with `sessionSecret`), from your server (Confirm a connect session), or in advance with `confirmInGame: false`.\n\n**Already connected.** When this player is already connected at the verified level with the member's own approval, the session is approved immediately: `status` is `approved`, `alreadyConnected` is `true`, and `url`, `qrUrl` and `code` are `null`.\n\n**Age.** A game set up for a mixed audience must send `underAge`. `true` returns `403`, stores nothing and ends a connection the player has.\n\nIt takes no `idempotencyKey`: a second call creates a second session and ends the first.\n\n**Limit.** 600 requests a minute for the game, across the Connect operations, and not counted against the key's own number.", "operationId": "createConnectSession", "x-required-scope": [ "players:connect" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectSessionRequest" }, "examples": { "request": { "summary": "A request", "value": { "playerId": "p_19", "playerName": "Nova77", "returnTo": "game" } } } } } }, "responses": { "200": { "description": "The session. With `code` it is the session of the member who created the code.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartedConnectSessionResponse" }, "examples": { "started": { "summary": "A new session", "value": { "success": true, "data": { "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN", "url": "https://ceejay.communitystudios.xyz/connect/s/kT3v9QmZ1xY7bLw2RfA8cN", "qrUrl": "https://ceejay.communitystudios.xyz/connect/s/kT3v9QmZ1xY7bLw2RfA8cN/qr", "code": "K7M-2QX", "sessionSecret": "ceejay_cs_4f8a2c1e9b7d3e41f8a6b0c1d25f0c2a9b7d3e41f8a6b0c1d24f8a2c1e9b7d3e", "expiresAt": "2026-10-08T18:14:11.000Z", "status": "pending", "alreadyConnected": false, "member": null } } }, "withCode": { "summary": "A player attached to a member's code", "value": { "success": true, "data": { "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN", "url": null, "qrUrl": null, "code": null, "sessionSecret": "ceejay_cs_4f8a2c1e9b7d3e41f8a6b0c1d25f0c2a9b7d3e41f8a6b0c1d24f8a2c1e9b7d3e", "expiresAt": "2026-10-08T18:14:11.000Z", "status": "needs_game_confirmation", "alreadyConnected": false, "member": { "displayName": "Nova", "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f60718293a4b5c6d7e8f90.png" } } } } } } } }, "400": { "description": "The request was refused and nothing was started. The game in the path is looked up after the body is read and before the fields are checked. The fields are then checked in this order: `playerId`, `playerName`, `code`, `returnTo`, `locale`, `underAge`, `confirmInGame`, then the age check of a game for a mixed audience.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badPlayerId": { "summary": "A player ID outside the alphabet", "value": { "error": "playerId must be 1 to 128 characters: letters, digits and . _ : @ | + = -, starting with a letter or a digit", "code": "bad_player_id", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badName": { "summary": "A name that is not text, or is too long", "value": { "error": "playerName must be text of at most 80 characters", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "playerName" } }, "badCode": { "summary": "A code that is not text", "value": { "error": "code must be text", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "code" } }, "unknownReturn": { "summary": "A return key the game does not have", "value": { "error": "returnTo is not one of the return addresses saved for this game", "code": "unknown_return", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badLocale": { "summary": "A locale that is not a language tag", "value": { "error": "locale must be a language tag such as en or pt-BR", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "locale" } }, "badUnderAge": { "summary": "An age value that is not true or false", "value": { "error": "underAge must be true or false", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "underAge" } }, "badConfirmInGame": { "summary": "confirmInGame is not true or false", "value": { "error": "confirmInGame must be true or false", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "confirmInGame" } }, "ageAnswerRequired": { "summary": "No age value for a game with a mixed audience", "value": { "error": "This game is for a mixed audience, so underAge must be sent as true or false", "code": "age_answer_required", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:connect` (`insufficient_scope`: the body adds `required` and `granted`, and a `*` key does not hold this scope), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`). Or the player is under age (`under_age`): nothing is stored, and a connection the player had is ended.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "*" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "underAge": { "summary": "The player is under age", "value": { "error": "This player cannot be connected", "code": "under_age", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`). Or no open request has the `code` you sent (`code_not_found`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "codeNotFound": { "summary": "No open request has this code", "value": { "error": "No open request has this code", "code": "code_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/ConnectMethodNotAllowed" }, "409": { "description": "The game is paused or suspended (`game_paused`), or the `code` belongs to an open request that was locked by this failed try, its fifth (`session_locked`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "gamePaused": { "summary": "The game is paused", "value": { "error": "This game is paused", "code": "game_paused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "sessionLocked": { "summary": "Locked after too many attempts", "value": { "error": "This request was locked after too many attempts. Start again", "code": "session_locked", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/ConnectRateLimited" }, "500": { "$ref": "#/components/responses/ConnectInternalError" } } }, "get": { "tags": [ "Connect" ], "summary": "List connect sessions", "description": "Reads up to 100 connect sessions of one game by their IDs, for a server that follows several at once.\n\n**Required scope:** `players:connect`. A key with the `*` scope does not include it: tick **Act for a player** when you create the key.\n\nSend the IDs as `ids`, separated by commas. An ID of another game or community is left out of the response, and so is one that does not exist. The whole list is returned in one response, so `page.nextCursor` is always `null` and `page.limit` is the number of sessions in it.\n\nA paused game can still be read.\n\n**Limit.** 600 requests a minute for the game, across the Connect operations, and not counted against the key's own number.", "operationId": "listConnectSessions", "x-required-scope": [ "players:connect" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" }, { "name": "ids", "in": "query", "required": true, "description": "The IDs of 1 to 100 connect sessions, separated by commas. Spaces around an ID are ignored.", "schema": { "type": "string" }, "example": "kT3v9QmZ1xY7bLw2RfA8cN,B8nLq2WxZ5cD7vJ1mK4pRs" } ], "responses": { "200": { "description": "The sessions that were found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectSessionsResponse" }, "examples": { "sessions": { "summary": "Two sessions", "value": { "success": true, "data": [ { "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN", "status": "approved", "reason": null, "expiresAt": "2026-10-08T18:14:11.000Z", "member": { "displayName": "Nova", "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f60718293a4b5c6d7e8f90.png" }, "connection": { "discordId": "409876543210987654", "playerId": "p_19", "proof": "verified", "connectedAt": "2026-10-08T18:06:40.000Z", "moved": false, "previousPlayerId": null } }, { "sessionId": "B8nLq2WxZ5cD7vJ1mK4pRs", "status": "expired", "reason": "expired", "expiresAt": "2026-10-08T17:40:02.000Z", "member": null, "connection": null } ], "page": { "nextCursor": null, "limit": 2 } } } } } } }, "400": { "description": "`ids` is missing or cannot be read. Nothing was looked up.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badIds": { "summary": "No IDs, too many, or one of another form", "value": { "error": "ids must be 1 to 100 session IDs, separated by commas", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "ids" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:connect` (`insufficient_scope`: the body adds `required` and `granted`, and a `*` key does not hold this scope), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "*" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/ConnectMethodNotAllowed" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" }, "500": { "$ref": "#/components/responses/ConnectInternalError" } } } }, "/games/{game}/connect/sessions/{sessionId}": { "get": { "tags": [ "Connect" ], "summary": "Get a connect session", "description": "Reads one connect session: its status, who approved, and the connection once it is approved.\n\n**Required scope:** `players:connect`. A key with the `*` scope does not include it: tick **Act for a player** when you create the key.\n\nA session a member's code was attached to is read by the same ID. A session past its 10 minutes reads `expired` whether or not it has been cleaned up. A paused game can still be read.\n\n**Limit.** 600 requests a minute for the game, across the Connect operations, and not counted against the key's own number.", "operationId": "getConnectSession", "x-required-scope": [ "players:connect" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" }, { "$ref": "#/components/parameters/ConnectSessionIdPath" } ], "responses": { "200": { "description": "The session.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSessionResponse" }, "examples": { "approved": { "summary": "An approved session", "value": { "success": true, "data": { "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN", "status": "approved", "reason": null, "expiresAt": "2026-10-08T18:14:11.000Z", "member": { "displayName": "Nova", "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f60718293a4b5c6d7e8f90.png" }, "connection": { "discordId": "409876543210987654", "playerId": "p_19", "proof": "verified", "connectedAt": "2026-10-08T18:06:40.000Z", "moved": false, "previousPlayerId": null } } } }, "waitingForGame": { "summary": "Waiting for the game to confirm", "value": { "success": true, "data": { "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN", "status": "needs_game_confirmation", "reason": null, "expiresAt": "2026-10-08T18:14:11.000Z", "member": { "displayName": "Nova", "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f60718293a4b5c6d7e8f90.png" }, "connection": null } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:connect` (`insufficient_scope`: the body adds `required` and `granted`, and a `*` key does not hold this scope), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "*" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`). Or the game has no session with this ID (`session_not_found`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "sessionNotFound": { "summary": "No such session", "value": { "error": "Connect session not found", "code": "session_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/ConnectMethodNotAllowed" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" }, "500": { "$ref": "#/components/responses/ConnectInternalError" } } } }, "/games/{game}/connect/sessions/{sessionId}/confirm": { "post": { "tags": [ "Connect" ], "summary": "Confirm a connect session", "description": "Approves or declines a connect session from your server, for a game client that holds no session secret.\n\n**Required scope:** `players:connect`. A key with the `*` scope does not include it: tick **Act for a player** when you create the key.\n\nRead the session first, show your player the Discord name it returns, and send the player's decision. `accept: true` is accepted only while `status` is `needs_game_confirmation`. For a session your server or the game started it finishes the session and saves the connection. For one a member started in Discord it moves the session to `needs_confirmation`, and the member confirms there. `accept: false` ends an open session in any state, with the reason `game_declined`.\n\nSafe to repeat, and it takes no `idempotencyKey`: confirming twice returns the session as it is, and declining a session that has ended changes nothing.\n\nThe response is the session, in the same shape that Get a connect session returns. A paused game can still decline.\n\n**Limit.** 600 requests a minute for the game, across the Connect operations, and not counted against the key's own number.", "operationId": "confirmConnectSession", "x-required-scope": [ "players:connect" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" }, { "$ref": "#/components/parameters/ConnectSessionIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmConnectSessionRequest" }, "examples": { "request": { "summary": "A request", "value": { "accept": true } } } } } }, "responses": { "200": { "description": "The session after it was approved or declined.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSessionResponse" }, "examples": { "approved": { "summary": "An approved session", "value": { "success": true, "data": { "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN", "status": "approved", "reason": null, "expiresAt": "2026-10-08T18:14:11.000Z", "member": { "displayName": "Nova", "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f60718293a4b5c6d7e8f90.png" }, "connection": { "discordId": "409876543210987654", "playerId": "p_19", "proof": "verified", "connectedAt": "2026-10-08T18:06:40.000Z", "moved": false, "previousPlayerId": null } } } } } } } }, "400": { "description": "The request was refused and nothing was changed. The checks run in this order: the body, then `accept`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badAccept": { "summary": "accept is not true or false", "value": { "error": "accept must be true or false", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "accept" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:connect` (`insufficient_scope`: the body adds `required` and `granted`, and a `*` key does not hold this scope), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "*" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`). Or the game has no session with this ID (`session_not_found`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "sessionNotFound": { "summary": "No such session", "value": { "error": "Connect session not found", "code": "session_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/ConnectMethodNotAllowed" }, "409": { "description": "The confirmation was not accepted. The session is not waiting for the game (`nothing_to_confirm`), it changed since the member approved (`session_changed`), the player is blocked (`player_blocked`) or connected to another Discord account (`player_taken`), or the game is paused (`game_paused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/ConnectRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/ConnectRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "nothingToConfirm": { "summary": "Not waiting for the game", "value": { "error": "There is nothing to confirm on this request right now", "code": "nothing_to_confirm", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "sessionChanged": { "summary": "The session changed", "value": { "error": "This request changed since it was shown. Read it again", "code": "session_changed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "playerBlocked": { "summary": "The community blocked the player", "value": { "error": "This player cannot be connected until the community lifts a block", "code": "player_blocked", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "playerTaken": { "summary": "The player is connected to another Discord account", "value": { "error": "This player is connected to another Discord account. Connect from the game the player is signed in to", "code": "player_taken", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gamePaused": { "summary": "The game is paused", "value": { "error": "This game is paused", "code": "game_paused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/ConnectRateLimited" }, "500": { "$ref": "#/components/responses/ConnectInternalError" } } } }, "/games/{game}/players/{playerId}": { "get": { "tags": [ "Players" ], "summary": "Get a player", "description": "Reads one player of a game: who they are connected to, the member summary, and the game's approved fields that are not sensitive.\n\n**Required scope:** `players:read` (a key with the `*` scope can also call it).\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. A player is found by the game's own ID, matched case-insensitively. `fields` holds the fields that are approved and not sensitive and have a current value, by their fixed keys, with numbers as numbers and yes or no fields as `true` or `false`. A sensitive field is never returned: no scope adds it. `member` is `null` when CEEJAY has no profile for the member. When `player.membership` is neither `member` nor `pending`, `member` is `null` and `fields` is empty as well: consent covers server members only.\n\nA player with no active connection is `404` with the code `player_not_found`. When the game holds data for players who have not connected and has some for this ID, the body adds `held: true`: the data is not returned.\n\nA paused game can still be read. It is counted against the key's own requests per minute (60 unless a higher limit was set on it).", "operationId": "getPlayer", "x-required-scope": [ "players:read" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" }, { "$ref": "#/components/parameters/PlayerIdPath" } ], "responses": { "200": { "description": "The player.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerDetailResponse" }, "examples": { "player": { "summary": "A verified player", "value": { "success": true, "data": { "player": { "playerId": "p_19", "discordId": "409876543210987654", "playerName": "Nova77", "proof": "verified", "origin": "connect", "connectedAt": "2026-10-08T18:06:40.000Z", "membership": "member", "sharing": { "agreed": [ "progress", "activity" ], "needed": [] } }, "member": { "displayName": "Nova", "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f60718293a4b5c6d7e8f90.png", "level": 12, "xp": 5420, "coins": 1450 }, "fields": { "std.level": 14, "std.last_played": "2026-10-07", "league_position": 3, "club": "Harbour Town" } } } } } } } }, "400": { "description": "The player ID in the URL path contains a character that is not allowed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badPlayerId": { "summary": "A player ID outside the alphabet", "value": { "error": "playerId must be 1 to 128 characters: letters, digits and . _ : @ | + = -, starting with a letter or a digit", "code": "bad_player_id", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:read` (`insufficient_scope`: the body adds `required` and `granted`), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:read", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:read" ], "granted": [ "xp:grant" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`). Or no connected player has this ID (`player_not_found`). When the game holds data for the ID, the body adds `held: true`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerNotFoundErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "playerNotFound": { "summary": "No connected player has this ID", "value": { "error": "No connected player has this playerId", "code": "player_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "playerHeld": { "summary": "The player is only held for a connection that has not happened", "value": { "error": "No connected player has this playerId", "code": "player_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "held": true } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/games/{game}/players": { "get": { "tags": [ "Players" ], "summary": "List players", "description": "Lists the players of a game who are connected to a Discord member, newest connection first, a page at a time.\n\n**Required scope:** `players:read` (a key with the `*` scope can also call it).\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. The list contains each player's `playerId`, `discordId`, `playerName`, `proof`, `origin`, `connectedAt` and `membership`. Read one player with Get a player for the member summary and the fields. A player who has not connected is not in the list. The response is the list in `data` with `page` alongside it: send `page.nextCursor` back as `cursor` for the next page, and stop when it is `null`.\n\nA paused game can still be read. It is counted against the key's own requests per minute (60 unless a higher limit was set on it).", "operationId": "listPlayers", "x-required-scope": [ "players:read" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" }, { "name": "limit", "in": "query", "required": false, "description": "The page size, from 1 to 200, written in digits. A value above 200 is lowered to 200, and `0`, an empty value or none gives 50. A negative number, a fraction or text is refused with `400`.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "required": false, "description": "Where the page starts: the `page.nextCursor` of the page before, sent back exactly as returned. Leave it out for the first page. A cursor that cannot be read, or an empty one, is refused with `400`.", "schema": { "type": "string", "maxLength": 512 }, "example": "WzQyXQ" } ], "responses": { "200": { "description": "A page of players.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPlayersResponse" }, "examples": { "players": { "summary": "Two players", "value": { "success": true, "data": [ { "playerId": "p_19", "discordId": "409876543210987654", "playerName": "Nova77", "proof": "verified", "origin": "connect", "connectedAt": "2026-10-08T18:06:40.000Z", "membership": "member" }, { "playerId": "p_77", "discordId": "521776109822345216", "playerName": null, "proof": "basic", "origin": "connect", "connectedAt": "2026-10-08T17:41:12.000Z", "membership": "pending" } ], "page": { "nextCursor": "WzQyXQ", "limit": 2 } } } } } } }, "400": { "description": "`limit` is not a whole number of 0 or more written in digits, or sent more than once, or `cursor` cannot be read. Nothing was looked up.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badLimit": { "summary": "Invalid limit", "value": { "error": "limit must be a whole number of 0 or more", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "limit" } }, "badCursor": { "summary": "A cursor that cannot be read", "value": { "error": "cursor is not one this list gave", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "cursor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:read` (`insufficient_scope`: the body adds `required` and `granted`), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:read", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:read" ], "granted": [ "xp:grant" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/games/{game}/players/{playerId}/disconnect": { "post": { "tags": [ "Players" ], "summary": "Disconnect a player", "description": "Ends a player's connection from your server. The member's connected role is removed, the player's devices are signed out, and the event `player.disconnected` is sent shortly afterwards.\n\n**Required scope:** `players:connect`. A key with the `*` scope does not hold it: tick it by name when you make the key.\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. The request takes no body. A player with no active connection is `404` with the code `player_not_found`. A reward already granted is not revoked. The values CEEJAY stores for the player are cleared from the member, and the member can connect again. It takes no `idempotencyKey`: ending a connection that has ended finds nothing to end.\n\nPlayers of a paused game, and of a game made for children, can still be disconnected. It is counted against the key's own requests per minute (60 unless a higher limit was set on it).", "operationId": "disconnectPlayerByKey", "x-required-scope": [ "players:connect" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" }, { "$ref": "#/components/parameters/PlayerIdPath" } ], "responses": { "200": { "description": "The connection was ended.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectPlayerResponse" }, "examples": { "disconnected": { "summary": "A connection ended", "value": { "success": true, "data": { "disconnected": true } } } } } } }, "400": { "description": "The player ID in the URL path contains a character that is not allowed, or a body was sent that is not a JSON object.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badPlayerId": { "summary": "A player ID outside the alphabet", "value": { "error": "playerId must be 1 to 128 characters: letters, digits and . _ : @ | + = -, starting with a letter or a digit", "code": "bad_player_id", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:connect` (`insufficient_scope`: the body adds `required` and `granted`, and a `*` key does not hold this scope), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "xp:grant" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`). Or no active connection exists for this player (`player_not_found`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "playerNotFound": { "summary": "No connected player has this ID", "value": { "error": "No connected player has this playerId", "code": "player_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/games/{game}/players/{playerId}/delete": { "post": { "tags": [ "Players" ], "summary": "Delete a player", "description": "Deletes what CEEJAY stores for one player ID in one game. Use it when a player asks for their data to be erased.\n\n**Required scope:** `players:delete`. A key with the `*` scope does not hold it: tick it by name when you make the key.\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. First the player's connection is ended and the bot is given up to 5 seconds to remove the connected role and send `player.disconnected`. Then these are removed: every connection of this player in this game, and its refresh tokens and consent details; the member's values for this game's fields, current and older; the player's game events in the member history, and the entries that say the player connected or disconnected; the connection log for this game and member; the player ID from the previous player of a moved connection; the player's connect sessions and passes; work still queued for the player; and everything held for the player if they had not connected. For the purchases the player made through the game, the player's ID, proof, connection and device are removed from the purchase and from what the game spent (the coins spent stay: they belong to the member), and the idempotency keys stored for the player's connections are removed.\n\nWhat stays: rewards already granted (they store a hash and never the ID, so \"once per player\" still holds), a restriction set by the community, and an `erased` marker, so data the game sends later for this ID is not held again. The request log of this request contains the route, not the ID.\n\nIt is a `POST` of its own, not a `DELETE`, because the scope it needs is for the whole route. Safe to repeat: when nothing is found it returns `200` with zeros. It takes no `idempotencyKey`.\n\nDeleting a player is available for paused games and games made for children too. It is counted against the key's own requests per minute (60 unless a higher limit was set on it).", "operationId": "deletePlayer", "x-required-scope": [ "players:delete" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" }, { "$ref": "#/components/parameters/PlayerIdPath" } ], "responses": { "200": { "description": "What was deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePlayerResponse" }, "examples": { "deleted": { "summary": "A player deleted", "value": { "success": true, "data": { "deleted": true, "removed": { "connection": 1, "values": 6, "events": 12, "pending": 0, "purchases": 2 } } } } } } } }, "400": { "description": "The player ID in the URL path contains a character that is not allowed, or a body was sent that is not a JSON object.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "badPlayerId": { "summary": "A player ID outside the alphabet", "value": { "error": "playerId must be 1 to 128 characters: letters, digits and . _ : @ | + = -, starting with a letter or a digit", "code": "bad_player_id", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:delete` (`insufficient_scope`: the body adds `required` and `granted`, and a `*` key does not hold this scope), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:delete", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:delete" ], "granted": [ "xp:grant" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/games/{game}/player-fields": { "post": { "tags": [ "Players" ], "summary": "Set player fields", "description": "Sends values about your players, to be stored on the members they are connected to: a league position, a club, the day a player last played. Up to 500 players in one call, each with up to 40 fields.\n\n**Required scope:** `players:write` (a key with the `*` scope can also call it).\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. Fields are **set**, not added: a value that equals the current one is not a new history entry, `null` clears a field, and a field that is not in the object is left as it is. A name is matched to the name your game uses for the field first, then to the field's key, case-insensitively. A name nothing matches is added to the field map as a proposal and returns `not_approved`; its value is written once the community's team approves it. Seven standard fields (the ones that need no choices) are approved by the first value.\n\nA value is text (up to 500 characters), a finite number (beyond 1e15 either way it is refused, and it is multiplied by the field's scale and rounded to 6 places), `true` or `false`, or `null`. A date is `YYYY-MM-DD`, or a full time with an offset, which becomes its UTC day. A dropdown accepts one of its choices, after your game's value is mapped through the field's value map. An object or a list is refused with `bad_value`.\n\nValues are stored for **members** only: a connected player whose member is not in the server gets the status `not_member`. A player who has not connected is `not_connected`, or `held` when the game holds data for players who have not. A connection a member made through Connect stores the categories the member consented to, and a field of another category is `not_consented`. A connection your own server created stores none, and your server is responsible for the consent. A connection made at the basic level, where the game supplied an unverified player ID, does not accept fields of the `purchases` or `location` category: each such field is a problem with the code `needs_verified_proof`, and the player's other fields are still written. Fields of `progress` and players your own server linked are not affected.\n\n`underAge: true` on a player stores nothing and ends their connection. It needs the key to hold `players:connect` as well: without it the whole call is `403` with the code `insufficient_scope` and `required: [\"players:connect\"]`, and nothing is written. A call can carry at most 50 players with `underAge: true`, or it is `400` with the code `bad_request`.\n\nA batch with problems still returns `200`, with a result for each player. Only a body that is not shaped right is `400`. The body is read before it is parsed, up to 512 KB; a larger one is `413`. With `dryRun: true` every check runs and nothing is written.\n\nIt takes no `idempotencyKey`: a field is set, not added, so sending it again changes nothing. It is counted against the key's own requests per minute (60 unless a higher limit was set on it). A batch of 500 players is one request.", "operationId": "setPlayerFields", "x-required-scope": [ "players:write" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPlayerFieldsRequest" }, "examples": { "request": { "summary": "Two players", "value": { "players": [ { "playerId": "p_19", "fields": { "league_position": 3, "club": "Harbour Town", "last_played": "2026-10-07T21:10:00+02:00", "coach_notes": "Ready for the cup" } }, { "playerId": "p_77", "fields": { "league_position": 9 } } ], "dryRun": false } } } } } }, "responses": { "200": { "description": "What happened to each player.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPlayerFieldsResponse" }, "examples": { "results": { "summary": "One written, one not connected", "value": { "success": true, "data": { "results": [ { "index": 0, "playerId": "p_19", "status": "written", "written": 2, "unchanged": 1, "cleared": 0, "problems": [ { "field": "coach_notes", "code": "not_approved" } ] }, { "index": 1, "playerId": "p_77", "status": "not_connected", "written": 0, "unchanged": 0, "cleared": 0, "problems": [] } ], "summary": { "players": 2, "written": 2, "unchanged": 1, "cleared": 0, "held": 0, "refused": 1 } } } } } } } }, "400": { "description": "The body is not shaped right. Nothing was looked up or written. A player that cannot be read is not an error of the call: it gets the status `bad_item` in the results.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notJson": { "summary": "The body is not JSON", "value": { "error": "The request body must be JSON", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noPlayers": { "summary": "No players", "value": { "error": "players must be a list of 1 to 500 players", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "players" } }, "tooManyPlayers": { "summary": "More than 500 players", "value": { "error": "A call can carry up to 500 players", "code": "too_many_players", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "tooManyUnderAge": { "summary": "More than 50 players with underAge", "value": { "error": "A call can carry up to 50 players with underAge: true", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "players" } }, "badDryRun": { "summary": "dryRun that is not true or false", "value": { "error": "dryRun must be true or false", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "dryRun" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:write` (`insufficient_scope`: the body adds `required` and `granted`), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`). It also returns `insufficient_scope` with `required: [\"players:connect\"]` when an entry says `underAge: true` and the key does not hold `players:connect`; a `*` key does not hold it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:write", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:write" ], "granted": [ "xp:grant" ] } }, "missingConnectScope": { "summary": "underAge without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "players:write" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The game is paused or suspended (`game_paused`). Nothing was written.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "gamePaused": { "summary": "The game is paused", "value": { "error": "This game is paused", "code": "game_paused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "413": { "description": "The body is larger than 512 KB. It is read before it is parsed, and nothing was looked at or written. Send fewer players or events in one call.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "tooLarge": { "summary": "A body over 512 KB", "value": { "error": "The request body is larger than 512 KB. Send fewer players or events in one call", "code": "body_too_large", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/games/{game}/player-events": { "post": { "tags": [ "Players" ], "summary": "Log player events", "description": "Logs things your players did in the game, to be shown on the profile of the member they are connected to, counted in segments, and rewarded. Up to 500 events in one call.\n\n**Required scope:** `players:write` (a key with the `*` scope can also call it).\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. Each event names a player (`playerId` or `discordId`), an `eventId` of your own and an `event`. The `eventId` is what makes a retry safe: events are idempotent on `eventId`, so a repeated ID is ignored and its status is `duplicate`. An event name that is not approved in the field map is not stored: it is proposed, gets the status `not_approved`, and can be sent again after approval, within 7 days. `occurredAt` can be at most 5 minutes ahead and at most 7 days back.\n\nEvents are stored for **members** only (`not_member` otherwise), and a player who has not connected is `not_connected`, or `held` when the game holds data for players who have not. The quantity of an event is stored only where its entry keeps one. Events take no free text: send money and other private values as fields, not as events. A member who has not consented to sharing the `activity` category, because they connected before the game shared it and have not consented since on their connections page, gets the status `not_consented`. A connection your own server created carries no consent and is not checked.\n\n`underAge: true` on an event stores nothing and ends the player's connection. It needs the key to hold `players:connect` as well: without it the whole call is `403` with the code `insufficient_scope` and `required: [\"players:connect\"]`. A call can carry at most 50 events with `underAge: true`, or it is `400` with the code `bad_request`.\n\nThe game has to share the `activity` category, or the whole call is `409` with the code `activity_not_shared`. The member history has to be enabled on this instance, or the call is `404` with the code `not_available` and `feature: \"member_history\"`. Over the game's events a minute (3,000 unless another number was set for the game) the whole call is `429` with the code `event_rate_exceeded`, `retryAfter` and a `Retry-After` header.\n\nAn event that earns a reward returns `reward: \"queued\"`: the call does not wait for the bot, which grants the reward asynchronously and only for a connection that meets the verification level the game requires. A reward is queued only for an event less than 24 hours old.\n\nThe body is read before it is parsed, up to 512 KB; a larger one is `413`. With `dryRun: true` every check runs and nothing is written or counted.\n\nIt takes no `idempotencyKey`: the `eventId` of each event is the key. It is counted against the key's own requests per minute (60 unless a higher limit was set on it). A batch of 500 events is one request.", "operationId": "logPlayerEvents", "x-required-scope": [ "players:write" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogPlayerEventsRequest" }, "examples": { "request": { "summary": "Two events", "value": { "events": [ { "eventId": "m-88213", "playerId": "p_19", "event": "match_won", "occurredAt": "2026-10-07T19:02:00Z", "quantity": 1 }, { "eventId": "m-88214", "playerId": "p_77", "event": "match_won", "occurredAt": "2026-10-07T19:05:00Z" } ], "dryRun": false } } } } } }, "responses": { "200": { "description": "What happened to each event.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogPlayerEventsResponse" }, "examples": { "results": { "summary": "One logged with a reward, one not connected", "value": { "success": true, "data": { "results": [ { "index": 0, "eventId": "m-88213", "status": "logged", "reward": "queued" }, { "index": 1, "eventId": "m-88214", "status": "not_connected", "reward": "none" } ], "summary": { "logged": 1, "duplicate": 0, "held": 0, "refused": 1, "rewardsQueued": 1 } } } } } } } }, "400": { "description": "The body is not shaped right. Nothing was looked up or written. An event that cannot be read is not an error of the call: it gets the status `bad_item` in the results.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "notJson": { "summary": "The body is not JSON", "value": { "error": "The request body must be JSON", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "noEvents": { "summary": "No events", "value": { "error": "events must be a list of 1 to 500 events", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "events" } }, "tooManyEvents": { "summary": "More than 500 events", "value": { "error": "A call can carry up to 500 events", "code": "too_many_events", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "tooManyUnderAge": { "summary": "More than 50 events with underAge", "value": { "error": "A call can carry up to 50 events with underAge: true", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "events" } }, "badDryRun": { "summary": "dryRun that is not true or false", "value": { "error": "dryRun must be true or false", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "dryRun" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:write` (`insufficient_scope`: the body adds `required` and `granted`), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`). It also returns `insufficient_scope` with `required: [\"players:connect\"]` when an entry says `underAge: true` and the key does not hold `players:connect`; a `*` key does not hold it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:write", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:write" ], "granted": [ "xp:grant" ] } }, "missingConnectScope": { "summary": "underAge without players:connect", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:connect" ], "granted": [ "players:write" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`). Or the member history is disabled on this instance (`not_available`, with `feature: \"member_history\"`): events are stored in it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "memberHistoryOff": { "summary": "The member history is switched off here", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "member_history" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The game is paused or suspended (`game_paused`), or it does not share the `activity` category (`activity_not_shared`). Nothing was written.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "gamePaused": { "summary": "The game is paused", "value": { "error": "This game is paused", "code": "game_paused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "activityNotShared": { "summary": "The game does not share activity", "value": { "error": "This game does not share the activity category, so events cannot be logged. The team adds it to what the game shares first", "code": "activity_not_shared", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "413": { "description": "The body is larger than 512 KB. It is read before it is parsed, and nothing was looked at or written. Send fewer players or events in one call.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "tooLarge": { "summary": "A body over 512 KB", "value": { "error": "The request body is larger than 512 KB. Send fewer players or events in one call", "code": "body_too_large", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "description": "The key has used up its requests for this minute (`rate_limited`), or the game sent more events this minute than it is allowed (`event_rate_exceeded`). `Retry-After`, `X-RateLimit-Reset` for the first and `retryAfter` say how many seconds are left. Nothing was written.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" }, "examples": { "limited": { "summary": "Too many requests", "value": { "error": "Rate limit exceeded", "code": "rate_limited", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 34 } }, "eventRate": { "summary": "Too many events this minute", "value": { "error": "This game has sent more events this minute than it is allowed. Wait and send them again", "code": "event_rate_exceeded", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "retryAfter": 41 } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/games/{game}/field-map": { "get": { "tags": [ "Field map" ], "summary": "Get the field map", "description": "Reads a game's field map: every field and event the game sends, with the state each is in.\n\n**Required scope:** `players:read` (a key with the `*` scope can also call it).\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. The map starts with the 14 standard fields. A name your game sends that nothing matches becomes a **proposed** entry; the community's team **approves** it (and chooses its type, choices and category) or leaves it **unused**. A key can read the map and propose to it, and cannot approve its own map. Seven standard fields that need no choices are approved by the first value your game sends for them. A game can have 25 approved fields of its own and 25 approved events, besides the standard fields, and up to 50 proposed entries of each kind at a time.\n\nNo value of a player, no sample and no value waiting for a choice is in the map: those are players' values that nobody has marked sensitive or not.\n\nA paused game can still be read. It is counted against the key's own requests per minute (60 unless a higher limit was set on it).", "operationId": "getFieldMap", "x-required-scope": [ "players:read" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" } ], "responses": { "200": { "description": "The field map.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldMapResponse" }, "examples": { "map": { "summary": "A map with approved and proposed entries", "value": { "success": true, "data": { "fields": [ { "sourceKey": "level", "options": [], "unit": null, "scale": null, "category": "progress", "standard": true, "sensitive": false, "state": "approved", "key": "std.level", "name": "Game level", "type": "number" }, { "sourceKey": "last_played", "options": [], "unit": null, "scale": null, "category": "progress", "standard": true, "sensitive": false, "state": "approved", "key": "std.last_played", "name": "Last played", "type": "date" }, { "sourceKey": "league_position", "options": [], "unit": null, "scale": null, "category": "progress", "standard": false, "sensitive": false, "state": "approved", "key": "league_position", "name": "League position", "type": "number" }, { "sourceKey": "club", "options": [], "unit": null, "scale": null, "category": "progress", "standard": false, "sensitive": false, "state": "approved", "key": "club", "name": "Club", "type": "text" }, { "sourceKey": "lifetime_spend", "options": [], "unit": "USD", "scale": null, "category": "purchases", "standard": true, "sensitive": true, "state": "approved", "key": "std.total_spend", "name": "Total spend", "type": "number" }, { "sourceKey": "coins_spent_cents", "options": [], "unit": null, "scale": 0.01, "category": "progress", "standard": false, "sensitive": false, "state": "proposed", "key": "coins_spent_cents", "name": "Coins spent cents", "type": "number" } ], "events": [ { "key": "match_won", "sourceKey": "match_won", "label": "Won a match", "keepsQuantity": false, "state": "approved", "rewardMode": "each" }, { "key": "cup_entered", "sourceKey": "cup_entered", "label": "Entered the cup", "keepsQuantity": false, "state": "proposed", "rewardMode": "once" } ], "limits": { "ownFields": 25, "events": 25 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:read` (`insufficient_scope`: the body adds `required` and `granted`), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:read", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:read" ], "granted": [ "xp:grant" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/games/{game}/field-map/propose": { "post": { "tags": [ "Field map" ], "summary": "Propose to the field map", "description": "Tells CEEJAY which fields and events your game sends, before it sends them, so the community's team can approve them first.\n\n**Required scope:** `players:write` (a key with the `*` scope can also call it).\n\nThe request is for one game of the key's community, named in the URL path. The key may be limited to some games. Send names with an example value in `sample`, or say more in `fields` and `events`. It adds or updates **proposed** entries and returns the entries your request named as the map shows them now. It never modifies an approved entry or one the team marked unused: those are returned with the reason in `skipped`. The team is notified when a new entry is added to the map, at most once a day for each game.\n\nThe proposal is made by fixed rules, with no AI model, so no player value leaves CEEJAY. A name that is a known alias of a standard field maps to that standard field. `true` and `false` are yes or no, a number is a number, text that reads as a date is a date, and everything else is text. A name that ends in `_cents` proposes a scale of `0.01`. A key is generated from the name. An example value is stored as a sample for the team, truncated to 80 characters.\n\nAn API key cannot approve proposals. A team member does that in the dashboard. It takes no `idempotencyKey`: a name that is already proposed is matched, not created twice. It is counted against the key's own requests per minute (60 unless a higher limit was set on it).", "operationId": "proposeFieldMap", "x-required-scope": [ "players:write" ], "x-since": "1.1.0", "parameters": [ { "$ref": "#/components/parameters/GamePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeFieldMapRequest" }, "examples": { "request": { "summary": "Names with example values", "value": { "sample": { "fields": { "league_position": 3, "club": "Harbour Town", "coins_spent_cents": 12900 }, "events": [ "match_won", "cup_entered" ] } } } } } } }, "responses": { "200": { "description": "The proposal.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeFieldMapResponse" }, "examples": { "proposal": { "summary": "Three fields and two events proposed", "value": { "success": true, "data": { "fields": [ { "sourceKey": "league_position", "options": [], "unit": null, "scale": null, "category": "progress", "standard": false, "sensitive": false, "state": "proposed", "key": "league_position", "name": "League position", "type": "number" }, { "sourceKey": "club", "options": [], "unit": null, "scale": null, "category": "progress", "standard": false, "sensitive": false, "state": "proposed", "key": "club", "name": "Club", "type": "text" }, { "sourceKey": "coins_spent_cents", "options": [], "unit": null, "scale": 0.01, "category": "progress", "standard": false, "sensitive": false, "state": "proposed", "key": "coins_spent_cents", "name": "Coins spent cents", "type": "number" } ], "events": [ { "key": "match_won", "sourceKey": "match_won", "label": "Won a match", "keepsQuantity": false, "state": "proposed", "rewardMode": "once" }, { "key": "cup_entered", "sourceKey": "cup_entered", "label": "Entered the cup", "keepsQuantity": false, "state": "proposed", "rewardMode": "once" } ], "skipped": [] } } } } } } }, "400": { "description": "The body is not shaped right. Nothing was proposed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notObject": { "summary": "The body is not a JSON object", "value": { "error": "The request body must be a JSON object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "nothingToPropose": { "summary": "Nothing to propose", "value": { "error": "Send at least one field or event to propose, in sample, fields or events", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "fields" } }, "sampleNotObject": { "summary": "A sample that is not an object", "value": { "error": "sample must be an object", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "sample" } }, "badFieldType": { "summary": "A type that is not known", "value": { "error": "type must be one of: text, number, date, choice, yes_no, ordered", "code": "bad_request", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "field": "fields.type" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key does not hold `players:write` (`insufficient_scope`: the body adds `required` and `granted`), or the game cannot be used: the community removed CEEJAY (`community_not_active`), the key is limited to other games (`game_not_allowed`), or the game is made for children (`audience_not_allowed`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "missingScope": { "summary": "Key without players:write", "value": { "error": "Insufficient scopes", "code": "insufficient_scope", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "required": [ "players:write" ], "granted": [ "xp:grant" ] } }, "communityNotActive": { "summary": "The community removed CEEJAY", "value": { "error": "This community is no longer active on CEEJAY", "code": "community_not_active", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "gameNotAllowed": { "summary": "The key is limited to other games", "value": { "error": "This API key is limited to other games", "code": "game_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } }, "audienceNotAllowed": { "summary": "A game made for children", "value": { "error": "A game made for children cannot connect players or send player data", "code": "audience_not_allowed", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "404": { "description": "Something the request names is not there, or Connect is not enabled for this instance (`not_available`, with `feature: \"players\"`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAvailable": { "summary": "Connect is not enabled on this instance yet", "value": { "error": "This is not available on this instance yet.", "code": "not_available", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2", "feature": "players" } }, "gameNotFound": { "summary": "No such game", "value": { "error": "Game not found", "code": "game_not_found", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "description": "The game is paused or suspended (`game_paused`). Nothing was proposed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "gamePaused": { "summary": "The game is paused", "value": { "error": "This game is paused", "code": "game_paused", "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "webhooks": { "member.joined": { "post": { "tags": [ "Webhook events" ], "summary": "A member joined", "description": "Sent when someone joins your Discord server. It is sent after CEEJAY has worked out how they joined, which can take a moment. Not sent for bot accounts: adding a bot to the server sends nothing.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveMemberJoined", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "member.joined" }, "data": { "$ref": "#/components/schemas/MemberJoinedData" } } } ] }, "examples": { "delivery": { "summary": "A member joined", "value": { "event": "member.joined", "data": { "userId": "409876543210987654", "username": "nova", "joinedAt": "2026-10-01T09:14:22.118Z", "inviteType": "normal", "memberCount": 12842, "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a60" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "member.left": { "post": { "tags": [ "Webhook events" ], "summary": "A member left", "description": "Sent when someone leaves your Discord server or is removed from it. Not sent for bot accounts: removing a bot sends nothing.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveMemberLeft", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "member.left" }, "data": { "$ref": "#/components/schemas/MemberLeftData" } } } ] }, "examples": { "delivery": { "summary": "A member left", "value": { "event": "member.left", "data": { "userId": "409876543210987654", "username": "nova", "leftAt": "2026-10-01T09:14:22.118Z", "memberCount": 12841, "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a61" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "quest.completed": { "post": { "tags": [ "Webhook events" ], "summary": "A quest was completed", "description": "Sent when CEEJAY's bot completes a quest for a member. A completion made through `POST /quests/complete` does not send it. One made by Complete a quest task does, when it finishes the quest. It is sent for a quest completed in Discord and for one completed through the API (Complete a quest, or the last task of a quest through Complete a quest task). For a completion made through Complete a quest it is sent once, shortly after the answer; `rewards.roleGranted` is `false` when the quest's role had not been given yet at that moment, and no second event follows when it is.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveQuestCompleted", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "quest.completed" }, "data": { "$ref": "#/components/schemas/QuestCompletedData" } } } ] }, "examples": { "delivery": { "summary": "A quest was completed", "value": { "event": "quest.completed", "data": { "userId": "409876543210987654", "questId": 42, "questTitle": "Join the weekend tournament", "questType": "api_check", "rewards": { "xp": 500, "currency": 250, "badge": "Tournament player", "roleGranted": false }, "completedAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a62" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "ticket.created": { "post": { "tags": [ "Webhook events" ], "summary": "A ticket was opened", "description": "Sent when a member opens a support ticket.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveTicketCreated", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "ticket.created" }, "data": { "$ref": "#/components/schemas/TicketCreatedData" } } } ] }, "examples": { "delivery": { "summary": "A ticket was opened", "value": { "event": "ticket.created", "data": { "ticketId": 318, "ticketNumber": 42, "panelName": "Support", "userId": "409876543210987654", "username": "nova", "channelId": "718230049827100384", "createdAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a63" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "poll.voted": { "post": { "tags": [ "Webhook events" ], "summary": "A member voted in a poll", "description": "Sent when a member votes in a poll, once per member and poll: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receivePollVoted", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "poll.voted" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "polls" }, "action": { "const": "voted" }, "targetType": { "const": "poll" }, "targetId": { "description": "The poll's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member voted in a poll", "value": { "event": "poll.voted", "data": { "userId": "409876543210987654", "app": "polls", "action": "voted", "targetType": "poll", "targetId": "41", "targetName": null, "itemId": "41", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a64" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "form.submitted": { "post": { "tags": [ "Webhook events" ], "summary": "A member submitted a survey or form", "description": "Sent when a member submits a survey or form, once per member and form: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveFormSubmitted", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "form.submitted" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "forms" }, "action": { "const": "submitted" }, "targetType": { "const": "form" }, "targetId": { "description": "The form's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member submitted a survey or form", "value": { "event": "form.submitted", "data": { "userId": "409876543210987654", "app": "forms", "action": "submitted", "targetType": "form", "targetId": "12", "targetName": null, "itemId": "12", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a65" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "suggestion.posted": { "post": { "tags": [ "Webhook events" ], "summary": "A member posted a suggestion", "description": "Sent when a member posts a suggestion, once per member and suggestion: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveSuggestionPosted", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "suggestion.posted" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "upvote" }, "action": { "const": "suggested" }, "targetType": { "const": "suggestion" }, "targetId": { "description": "The suggestion's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member posted a suggestion", "value": { "event": "suggestion.posted", "data": { "userId": "409876543210987654", "app": "upvote", "action": "suggested", "targetType": "suggestion", "targetId": "208", "targetName": null, "itemId": null, "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a66" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "suggestion.upvoted": { "post": { "tags": [ "Webhook events" ], "summary": "A member upvoted a suggestion", "description": "Sent when a member upvotes a suggestion, once per member and suggestion: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveSuggestionUpvoted", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "suggestion.upvoted" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "upvote" }, "action": { "const": "upvoted" }, "targetType": { "const": "suggestion" }, "targetId": { "description": "The suggestion's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member upvoted a suggestion", "value": { "event": "suggestion.upvoted", "data": { "userId": "409876543210987654", "app": "upvote", "action": "upvoted", "targetType": "suggestion", "targetId": "208", "targetName": null, "itemId": null, "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a67" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "event.rsvp": { "post": { "tags": [ "Webhook events" ], "summary": "A member said they are going to an event", "description": "Sent when a member says they are going to an event, once per member and event: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveEventRsvp", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "event.rsvp" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "events" }, "action": { "const": "rsvp" }, "targetType": { "const": "event" }, "targetId": { "description": "The event's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member said they are going to an event", "value": { "event": "event.rsvp", "data": { "userId": "409876543210987654", "app": "events", "action": "rsvp", "targetType": "event", "targetId": "19", "targetName": null, "itemId": "19", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a68" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "event.attended": { "post": { "tags": [ "Webhook events" ], "summary": "A member attended an event", "description": "Sent when a member attends an event, once per member and event: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveEventAttended", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "event.attended" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "events" }, "action": { "const": "attended" }, "targetType": { "const": "event" }, "targetId": { "description": "The event's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member attended an event", "value": { "event": "event.attended", "data": { "userId": "409876543210987654", "app": "events", "action": "attended", "targetType": "event", "targetId": "19", "targetName": null, "itemId": "19", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a69" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "member.level_up": { "post": { "tags": [ "Webhook events" ], "summary": "A member reached a new level", "description": "Sent when a member reaches a new level, every time it happens.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveMemberLevelUp", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "member.level_up" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "xp" }, "action": { "const": "leveled_up" }, "targetType": { "type": "null" }, "targetId": { "type": "null" }, "quantity": { "type": "number", "description": "The level reached." } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member reached a new level", "value": { "event": "member.level_up", "data": { "userId": "409876543210987654", "app": "xp", "action": "leveled_up", "targetType": null, "targetId": null, "targetName": null, "itemId": null, "quantity": 13, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a60" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "badge.earned": { "post": { "tags": [ "Webhook events" ], "summary": "A member earned a badge", "description": "Sent when a member earns a badge, once per member and badge: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveBadgeEarned", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "badge.earned" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "achievements" }, "action": { "const": "earned_badge" }, "targetType": { "const": "badge" }, "targetId": { "description": "The badge's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member earned a badge", "value": { "event": "badge.earned", "data": { "userId": "409876543210987654", "app": "achievements", "action": "earned_badge", "targetType": "badge", "targetId": "7", "targetName": null, "itemId": "7", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a61" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "shop.purchased": { "post": { "tags": [ "Webhook events" ], "summary": "A member bought something from the shop", "description": "Sent when a member buys something from the shop, every time it happens.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveShopPurchased", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "shop.purchased" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "shop-economy" }, "action": { "const": "purchased" }, "targetType": { "const": "item" }, "targetId": { "description": "The shop item's ID." }, "quantity": { "type": "number", "description": "The price paid." } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member bought something from the shop", "value": { "event": "shop.purchased", "data": { "userId": "409876543210987654", "app": "shop-economy", "action": "purchased", "targetType": "item", "targetId": "15", "targetName": null, "itemId": "15", "quantity": 500, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a62" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "member.checked_in": { "post": { "tags": [ "Webhook events" ], "summary": "A member did their daily check-in", "description": "Sent when a member does their daily check-in, at most once per member per day.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveMemberCheckedIn", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "member.checked_in" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "shop-economy" }, "action": { "const": "checked_in" }, "targetType": { "type": "null" }, "targetId": { "type": "null" }, "quantity": { "type": "number", "description": "The length of the check-in streak." } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member did their daily check-in", "value": { "event": "member.checked_in", "data": { "userId": "409876543210987654", "app": "shop-economy", "action": "checked_in", "targetType": null, "targetId": null, "targetName": null, "itemId": null, "quantity": 5, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a63" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "giveaway.entered": { "post": { "tags": [ "Webhook events" ], "summary": "A member entered a giveaway", "description": "Sent when a member enters a giveaway, once per member and giveaway: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveGiveawayEntered", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "giveaway.entered" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "giveaways" }, "action": { "const": "entered" }, "targetType": { "const": "giveaway" }, "targetId": { "description": "The giveaway's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member entered a giveaway", "value": { "event": "giveaway.entered", "data": { "userId": "409876543210987654", "app": "giveaways", "action": "entered", "targetType": "giveaway", "targetId": "6", "targetName": null, "itemId": "6", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a64" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "giveaway.won": { "post": { "tags": [ "Webhook events" ], "summary": "A member won a giveaway", "description": "Sent when a member wins a giveaway, once per member and giveaway: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveGiveawayWon", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "giveaway.won" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "giveaways" }, "action": { "const": "won" }, "targetType": { "const": "giveaway" }, "targetId": { "description": "The giveaway's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member won a giveaway", "value": { "event": "giveaway.won", "data": { "userId": "409876543210987654", "app": "giveaways", "action": "won", "targetType": "giveaway", "targetId": "6", "targetName": null, "itemId": "6", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a65" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "reward.received": { "post": { "tags": [ "Webhook events" ], "summary": "A member received a reward", "description": "Sent when a member receives a reward, once per member and reward: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveRewardReceived", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "reward.received" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "rewards-engine" }, "action": { "const": "received_reward" }, "targetType": { "const": "reward" }, "targetId": { "description": "The ID of the reward's grant." }, "quantity": { "type": "number", "description": "The amount of the reward." } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member received a reward", "value": { "event": "reward.received", "data": { "userId": "409876543210987654", "app": "rewards-engine", "action": "received_reward", "targetType": "reward", "targetId": "5120", "targetName": null, "itemId": null, "quantity": 250, "occurredAt": "2026-10-01T09:14:22.118Z", "details": { "sourceKind": "level", "sourceId": "12", "rewardId": "9", "rewardType": "coins" }, "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a66" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "content.posted": { "post": { "tags": [ "Webhook events" ], "summary": "A member posted in a content channel", "description": "Sent when a member posts in a content channel, every time it happens.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveContentPosted", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "content.posted" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "ugc-content" }, "action": { "const": "posted" }, "targetType": { "const": "channel" }, "targetId": { "description": "The channel's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member posted in a content channel", "value": { "event": "content.posted", "data": { "userId": "409876543210987654", "app": "ugc-content", "action": "posted", "targetType": "channel", "targetId": "718230049827100384", "targetName": null, "itemId": null, "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a67" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "ticket.closed": { "post": { "tags": [ "Webhook events" ], "summary": "A member's ticket was closed", "description": "Sent when a member's ticket is closed, once per member and ticket: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveTicketClosed", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "ticket.closed" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "ticket-support" }, "action": { "const": "closed" }, "targetType": { "const": "ticket" }, "targetId": { "description": "The ticket's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member's ticket was closed", "value": { "event": "ticket.closed", "data": { "userId": "409876543210987654", "app": "ticket-support", "action": "closed", "targetType": "ticket", "targetId": "318", "targetName": null, "itemId": "2", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a68" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "program.joined": { "post": { "tags": [ "Webhook events" ], "summary": "A member joined a program", "description": "Sent when a member joins a program, once per member and program: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveProgramJoined", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "program.joined" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "programs" }, "action": { "const": "joined" }, "targetType": { "const": "program" }, "targetId": { "description": "The program's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member joined a program", "value": { "event": "program.joined", "data": { "userId": "409876543210987654", "app": "programs", "action": "joined", "targetType": "program", "targetId": "3", "targetName": null, "itemId": "3", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a69" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "account.linked": { "post": { "tags": [ "Webhook events" ], "summary": "A member linked an account on another platform", "description": "Sent when a member links an account on another platform, once per member and platform: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveAccountLinked", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "account.linked" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "connect" }, "action": { "const": "linked" }, "targetType": { "const": "platform" }, "targetId": { "description": "The platform, for example `steam`." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member linked an account on another platform", "value": { "event": "account.linked", "data": { "userId": "409876543210987654", "app": "connect", "action": "linked", "targetType": "platform", "targetId": "steam", "targetName": null, "itemId": null, "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a60" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "email.opened": { "post": { "tags": [ "Webhook events" ], "summary": "A member opened an email for the first time", "description": "Sent when a member opens an email for the first time, once per member and email: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveEmailOpened", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "email.opened" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "communication" }, "action": { "const": "opened_email" }, "targetType": { "const": "email" }, "targetId": { "description": "The email campaign's ID." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member opened an email for the first time", "value": { "event": "email.opened", "data": { "userId": "409876543210987654", "app": "communication", "action": "opened_email", "targetType": "email", "targetId": "27", "targetName": null, "itemId": "27", "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a61" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "role.picked": { "post": { "tags": [ "Webhook events" ], "summary": "A member picked a role", "description": "Sent when a member picks a role, every time it happens.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveRolePicked", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "role.picked" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "react-roles" }, "action": { "const": "picked_role" }, "targetType": { "const": "role" }, "targetId": { "description": "The ID of the role picked (the first, when several were picked at once)." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member picked a role", "value": { "event": "role.picked", "data": { "userId": "409876543210987654", "app": "react-roles", "action": "picked_role", "targetType": "role", "targetId": "982371004827100394", "targetName": null, "itemId": null, "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a62" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "member.verified": { "post": { "tags": [ "Webhook events" ], "summary": "A member passed verification", "description": "Sent when a member passes verification, once per member.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveMemberVerified", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "member.verified" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "onboarding" }, "action": { "const": "verified" }, "targetType": { "type": "null" }, "targetId": { "type": "null" }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member passed verification", "value": { "event": "member.verified", "data": { "userId": "409876543210987654", "app": "onboarding", "action": "verified", "targetType": null, "targetId": null, "targetName": null, "itemId": null, "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a63" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "member.invited": { "post": { "tags": [ "Webhook events" ], "summary": "A member invited someone who joined", "description": "Sent when a member invites someone who joins, once per member and invited member: doing it again sends nothing more.\n\nThis is a member-action event. It is sent when the action is added to the member's activity history, and only where that history is switched on (the dashboard only offers these events as choices there). An action that is added more than 10 minutes after it happened, when CEEJAY catches up on past activity, sends nothing. Every member-action event carries the same fields in `data`.\n\nDelivery, signing and retries are described in the introduction of this document and on the **Webhook events** tag.", "operationId": "receiveMemberInvited", "security": [], "parameters": [ { "$ref": "#/components/parameters/WebhookEventHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" }, { "$ref": "#/components/parameters/DeliveryAttemptHeader" }, { "$ref": "#/components/parameters/DeliveryTimestampHeader" }, { "$ref": "#/components/parameters/DeliverySignatureV2Header" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "member.invited" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MemberActionData" }, { "type": "object", "properties": { "app": { "const": "invite-tracking" }, "action": { "const": "invited" }, "targetType": { "const": "member" }, "targetId": { "description": "The Discord ID of the member who joined through the invite." }, "quantity": { "type": "null" } } } ] } } } ] }, "examples": { "delivery": { "summary": "A member invited someone who joined", "value": { "event": "member.invited", "data": { "userId": "409876543210987654", "app": "invite-tracking", "action": "invited", "targetType": "member", "targetId": "512345678901234567", "targetName": null, "itemId": null, "quantity": null, "occurredAt": "2026-10-01T09:14:22.118Z", "discordId": "409876543210987654" }, "serverId": "721104938271003842", "timestamp": "2026-10-01T09:14:22.431Z", "id": "evt_5b1f0c7e9a3d4e2f8c6a1b0d9e8f7a64" } } } } } }, "responses": { "2XX": { "description": "Acknowledge the delivery with any 2xx status within 5 seconds. The body is ignored." }, "default": { "description": "Any other status, a redirect (redirects are not followed) or no answer within 5 seconds counts as a failed delivery. It is tried again later." } } } }, "custom.event": { "post": { "tags": [ "Webhook events" ], "summary": "A custom event you emitted", "description": "Sent when you emit an event with `POST /events/emit`. Subscribe to `custom.event` to receive every custom event, to the exact name (for example `custom.purchase.completed`) to receive one, or to `*` to receive everything.\n\nThe `event` in the body and in the `X-CEEJAY-Event` header is the name you sent with `custom.` in front, not `custom.event`. `data` is exactly what you sent: CEEJAY adds nothing to it. Every subscription of one call receives the same `id` and `X-CEEJAY-Delivery`. The `id` looks like `evt_