{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "BotGG API", "version": "1.0.0", "summary": "Read and change the BotGG data of one Discord server from your own backend.", "description": "Server-to-server REST API of BotGG. Every request authenticates with a per-server API key (`Authorization: Bearer botgg_…`) created in the console (server → API). Keys are scoped; requests from browsers (with an `Origin` header) are refused. IDs are Discord snowflakes sent as strings. Errors are `{ \"error\": CODE, \"message\": \"…\" }`. Docs: https://botgg.app/developers/", "termsOfService": "https://botgg.app/terms/", "contact": { "name": "BotGG", "url": "https://botgg.app/contact/" } }, "servers": [ { "url": "https://console.botgg.app/api/v1", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "guild", "description": "Server endpoints.", "x-displayName": "Server", "x-botgg-label": { "en": "Server", "ru": "Сервер", "he": "שרת" } }, { "name": "bank", "description": "Bank endpoints.", "x-displayName": "Bank", "x-botgg-label": { "en": "Bank", "ru": "Банк", "he": "בנק" } }, { "name": "levels", "description": "Levels endpoints.", "x-displayName": "Levels", "x-botgg-label": { "en": "Levels", "ru": "Уровни", "he": "רמות" } }, { "name": "invites", "description": "Invites & Rewards endpoints.", "x-displayName": "Invites & Rewards", "x-botgg-label": { "en": "Invites & Rewards", "ru": "Приглашения и награды", "he": "הזמנות ותגמולים" } }, { "name": "shop", "description": "Shop endpoints.", "x-displayName": "Shop", "x-botgg-label": { "en": "Shop", "ru": "Магазин", "he": "חנות" } }, { "name": "giveaways", "description": "Giveaways endpoints.", "x-displayName": "Giveaways", "x-botgg-label": { "en": "Giveaways", "ru": "Розыгрыши", "he": "הגרלות" } }, { "name": "flows", "description": "Flows endpoints.", "x-displayName": "Flows", "x-botgg-label": { "en": "Flows", "ru": "Сценарии", "he": "תהליכים" } }, { "name": "tickets", "description": "Tickets endpoints.", "x-displayName": "Tickets", "x-botgg-label": { "en": "Tickets", "ru": "Тикеты", "he": "כרטיסים" } }, { "name": "applications", "description": "Applications endpoints.", "x-displayName": "Applications", "x-botgg-label": { "en": "Applications", "ru": "Заявки", "he": "מועמדויות" } }, { "name": "appeals", "description": "Ban appeals endpoints.", "x-displayName": "Ban appeals", "x-botgg-label": { "en": "Ban appeals", "ru": "Апелляции на бан", "he": "ערעורי הרחקה" } }, { "name": "moderation", "description": "Moderation endpoints.", "x-displayName": "Moderation", "x-botgg-label": { "en": "Moderation", "ru": "Модерация", "he": "ניהול" } }, { "name": "webhooks", "description": "Events BotGG sends to your HTTPS endpoint (signed).", "x-displayName": "Webhooks" } ], "paths": { "/guilds/{guildId}": { "get": { "operationId": "guildGet", "summary": "Get the server", "description": "Name, icon, approximate member count, the bot’s language and the enabled BotGG features.", "tags": [ "guild" ], "security": [ { "apiKey": [ "guild:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "iconUrl": { "type": [ "string", "null" ] }, "memberCount": { "type": [ "integer", "null" ], "description": "Approximate; null when Discord is unreachable" }, "locale": { "type": "string", "description": "The bot’s language on this server (en, ru, he)" }, "enabledFeatures": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "icon", "iconUrl", "memberCount", "locale", "enabledFeatures" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } } }, "x-botgg-id": "guild.get", "x-botgg-scope": "guild:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": null, "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "RATE_LIMITED", "INTERNAL" ] } }, "/guilds/{guildId}/roles": { "get": { "operationId": "guildListRoles", "summary": "List roles", "description": "Highest first (Discord order), without @everyone.", "tags": [ "guild" ], "security": [ { "apiKey": [ "guild:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "managed": { "type": "boolean" }, "hoist": { "type": "boolean" }, "mentionable": { "type": "boolean" } }, "required": [ "id", "name", "color", "position", "managed", "hoist", "mentionable" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "guild.listRoles", "x-botgg-scope": "guild:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": null, "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/channels": { "get": { "operationId": "guildListChannels", "summary": "List channels", "description": "In Discord’s sidebar order (categories followed by their channels); threads are not included.", "tags": [ "guild" ], "security": [ { "apiKey": [ "guild:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "voice", "category", "announcement", "stage", "forum", "media", "other" ] }, "parentId": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [ "id", "name", "type", "parentId", "position" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "guild.listChannels", "x-botgg-scope": "guild:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": null, "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/members/{userId}": { "get": { "operationId": "guildGetMember", "summary": "Get a member", "description": "Basic member info: names, avatar, role ids and join date. Cached for up to 5 minutes.", "tags": [ "guild" ], "security": [ { "apiKey": [ "guild:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "globalName": { "type": [ "string", "null" ] }, "nickname": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "bot": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Role ids" }, "joinedAt": { "type": [ "string", "null" ] } }, "required": [ "userId", "username", "globalName", "nickname", "displayName", "avatarUrl", "bot", "roles", "joinedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "guild.getMember", "x-botgg-scope": "guild:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": null, "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/bank/members/{userId}": { "get": { "operationId": "bankGetBalance", "summary": "Get a member’s balance", "description": "Members without an account yet get the server’s starting balance.", "tags": [ "bank" ], "security": [ { "apiKey": [ "bank:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "balance": { "type": "integer" }, "currency": { "type": "object", "properties": { "name": { "type": "string" }, "plural": { "type": "string" }, "emoji": { "type": [ "string", "null" ] } }, "required": [ "name", "plural", "emoji" ] } }, "required": [ "userId", "balance", "currency" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`BANK_DISABLED` — The Bank feature is turned off on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BANK_DISABLED" ] } } } ] }, "examples": { "BANK_DISABLED": { "value": { "error": "BANK_DISABLED", "message": "The Bank feature is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "bank.getBalance", "x-botgg-scope": "bank:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "bank", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "BANK_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/bank/members/{userId}/transactions": { "get": { "operationId": "bankListTransactions", "summary": "List a member’s transactions", "description": "Newest first. Pass `before=` for the next page.", "tags": [ "bank" ], "security": [ { "apiKey": [ "bank:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "amount": { "type": "integer" }, "balanceAfter": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "counterpartyId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "amount", "balanceAfter", "reason", "counterpartyId", "createdAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`BANK_DISABLED` — The Bank feature is turned off on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BANK_DISABLED" ] } } } ] }, "examples": { "BANK_DISABLED": { "value": { "error": "BANK_DISABLED", "message": "The Bank feature is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "bank.listTransactions", "x-botgg-scope": "bank:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "bank", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "BANK_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] }, "post": { "operationId": "bankCreateTransaction", "summary": "Add to or remove from a member’s balance", "description": "Same rules as a banker change. Logged in the Bank ledger (type `api`) and the Bank log channel.", "tags": [ "bank" ], "security": [ { "apiKey": [ "bank:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "add", "remove" ], "description": "add = credit, remove = debit" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "type": [ "string", "null" ], "maxLength": 200, "description": "Shown in the Bank ledger and log" } }, "required": [ "type", "amount" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "integer" }, "userId": { "type": "string" }, "type": { "type": "string", "enum": [ "add", "remove" ] }, "amount": { "type": "integer" }, "previousBalance": { "type": "integer" }, "balance": { "type": "integer" }, "createdAt": { "type": "string" } }, "required": [ "transactionId", "userId", "type", "amount", "previousBalance", "balance", "createdAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`BANK_DISABLED` — The Bank feature is turned off on the server.\n`INSUFFICIENT_FUNDS` — A remove would make the balance negative (`balance`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BANK_DISABLED", "INSUFFICIENT_FUNDS" ] } } } ] }, "examples": { "BANK_DISABLED": { "value": { "error": "BANK_DISABLED", "message": "The Bank feature is turned off on the server." } }, "INSUFFICIENT_FUNDS": { "value": { "error": "INSUFFICIENT_FUNDS", "message": "A remove would make the balance negative." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.\n`BOT_ACCOUNT` — Bots can’t hold a balance.\n`BALANCE_LIMIT` — The balance would exceed the maximum.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT", "BALANCE_LIMIT" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } }, "BOT_ACCOUNT": { "value": { "error": "BOT_ACCOUNT", "message": "Bots can’t hold a balance." } }, "BALANCE_LIMIT": { "value": { "error": "BALANCE_LIMIT", "message": "The balance would exceed the maximum." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "bank.createTransaction", "x-botgg-scope": "bank:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "bank", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "BANK_DISABLED", "INSUFFICIENT_FUNDS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT", "BALANCE_LIMIT", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/bank/leaderboard": { "get": { "operationId": "bankLeaderboard", "summary": "Top balances", "tags": [ "bank" ], "security": [ { "apiKey": [ "bank:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "userId": { "type": "string" }, "balance": { "type": "integer" } }, "required": [ "rank", "userId", "balance" ] } }, "currency": { "type": "object", "properties": { "name": { "type": "string" }, "plural": { "type": "string" }, "emoji": { "type": [ "string", "null" ] } }, "required": [ "name", "plural", "emoji" ] } }, "required": [ "items", "currency" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`BANK_DISABLED` — The Bank feature is turned off on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BANK_DISABLED" ] } } } ] }, "examples": { "BANK_DISABLED": { "value": { "error": "BANK_DISABLED", "message": "The Bank feature is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "bank.leaderboard", "x-botgg-scope": "bank:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "bank", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "BANK_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/levels/members/{userId}": { "get": { "operationId": "levelsGetMember", "summary": "Get a member’s level", "description": "Level, XP, progress and XP rank. Members without activity get zeros. Live activity can take a few seconds to show.", "tags": [ "levels" ], "security": [ { "apiKey": [ "levels:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "xp": { "type": "integer" }, "level": { "type": "integer" }, "xpIntoLevel": { "type": "integer" }, "xpForNext": { "type": "integer" }, "progress": { "type": "number", "description": "0–1 inside the current level" }, "messages": { "type": "integer" }, "voiceMinutes": { "type": "integer" }, "streak": { "type": "integer" }, "bestStreak": { "type": "integer" }, "rank": { "type": [ "integer", "null" ], "description": "By XP; null without XP" }, "hidden": { "type": "boolean", "description": "The member hid themselves from public leaderboards (/rank leaderboard:hide)" }, "lastXpAt": { "type": [ "string", "null" ] } }, "required": [ "userId", "xp", "level", "xpIntoLevel", "xpForNext", "progress", "messages", "voiceMinutes", "streak", "bestStreak", "rank", "hidden", "lastXpAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "levels.getMember", "x-botgg-scope": "levels:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "levels", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/levels/leaderboard": { "get": { "operationId": "levelsLeaderboard", "summary": "XP leaderboard", "description": "Highest XP first. Pass `cursor=` for the next page. Members who hid themselves from public leaderboards keep their rank but have `userId: null` — respect that if you publish the list.", "tags": [ "levels" ], "security": [ { "apiKey": [ "levels:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "userId": { "type": [ "string", "null" ], "description": "null for members who hid themselves from public leaderboards" }, "hidden": { "type": "boolean" }, "xp": { "type": "integer" }, "level": { "type": "integer" }, "messages": { "type": "integer" }, "voiceMinutes": { "type": "integer" } }, "required": [ "rank", "userId", "hidden", "xp", "level", "messages", "voiceMinutes" ] } }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "total", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "levels.leaderboard", "x-botgg-scope": "levels:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "levels", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/levels/members/{userId}/xp-changes": { "post": { "operationId": "levelsCreateXpChange", "summary": "Add, remove or set a member’s XP", "description": "Same as /levels give|take|set: the bot applies the change within a few seconds, then updates reward roles and posts level-up announcements. Answers 202 with a change id — poll GET …/levels/xp-changes/{changeId} for the result. Written to the audit log.", "tags": [ "levels" ], "security": [ { "apiKey": [ "levels:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "add", "remove", "set" ], "description": "add / remove = relative change, set = new total" }, "amount": { "type": "integer", "minimum": 0, "maximum": 2000000000 }, "unit": { "type": "string", "enum": [ "xp", "levels" ], "description": "Default `xp`. With `levels`, the progress inside the level is kept" }, "reason": { "type": [ "string", "null" ], "maxLength": 200, "description": "Shown in the audit log" } }, "required": [ "type", "amount" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "changeId": { "type": "string" }, "userId": { "type": "string" }, "type": { "type": "string", "enum": [ "add", "remove", "set" ] }, "unit": { "type": "string", "enum": [ "xp", "levels" ] }, "amount": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "processing", "done", "failed" ] }, "result": { "type": [ "object", "null" ], "properties": { "previousLevel": { "type": "integer" }, "level": { "type": "integer" }, "xp": { "type": "integer" } }, "required": [ "previousLevel", "level", "xp" ], "description": "When done" }, "error": { "type": [ "string", "null" ], "description": "When failed" }, "createdAt": { "type": "string" }, "processedAt": { "type": [ "string", "null" ] } }, "required": [ "changeId", "userId", "type", "unit", "amount", "status", "result", "error", "createdAt", "processedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.\n`BOT_ACCOUNT` — Bots can’t hold a balance.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } }, "BOT_ACCOUNT": { "value": { "error": "BOT_ACCOUNT", "message": "Bots can’t hold a balance." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "levels.createXpChange", "x-botgg-scope": "levels:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "levels", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/levels/xp-changes/{changeId}": { "get": { "operationId": "levelsGetXpChange", "summary": "Get the status of an XP change", "description": "Only changes made with the same API key. `done` includes the level before/after and the new XP total.", "tags": [ "levels" ], "security": [ { "apiKey": [ "levels:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "changeId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,18}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "changeId": { "type": "string" }, "userId": { "type": "string" }, "type": { "type": "string", "enum": [ "add", "remove", "set" ] }, "unit": { "type": "string", "enum": [ "xp", "levels" ] }, "amount": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "processing", "done", "failed" ] }, "result": { "type": [ "object", "null" ], "properties": { "previousLevel": { "type": "integer" }, "level": { "type": "integer" }, "xp": { "type": "integer" } }, "required": [ "previousLevel", "level", "xp" ], "description": "When done" }, "error": { "type": [ "string", "null" ], "description": "When failed" }, "createdAt": { "type": "string" }, "processedAt": { "type": [ "string", "null" ] } }, "required": [ "changeId", "userId", "type", "unit", "amount", "status", "result", "error", "createdAt", "processedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`XP_CHANGE_NOT_FOUND` — No XP change with this id was made with this API key.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "XP_CHANGE_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "XP_CHANGE_NOT_FOUND": { "value": { "error": "XP_CHANGE_NOT_FOUND", "message": "No XP change with this id was made with this API key." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "levels.getXpChange", "x-botgg-scope": "levels:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "levels", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "XP_CHANGE_NOT_FOUND", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/invites/members/{userId}": { "get": { "operationId": "invitesGetMember", "summary": "Get a member’s invites", "description": "Invite counters, all-time rank and the active season’s count and rank. Members who invited nobody get zeros.", "tags": [ "invites" ], "security": [ { "apiKey": [ "invites:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "invites": { "type": "integer", "description": "verified + bonus (never below 0) — what milestones and the leaderboard use" }, "verified": { "type": "integer" }, "pending": { "type": "integer" }, "left": { "type": "integer" }, "fake": { "type": "integer" }, "bonus": { "type": "integer" }, "total": { "type": "integer" }, "rank": { "type": [ "integer", "null" ] }, "season": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "startsAt": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ] }, "invites": { "type": "integer" }, "rank": { "type": [ "integer", "null" ] } }, "required": [ "id", "number", "name", "startsAt", "endsAt", "invites", "rank" ], "description": "The active season, if any" } }, "required": [ "userId", "invites", "verified", "pending", "left", "fake", "bonus", "total", "rank", "season" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "invites.getMember", "x-botgg-scope": "invites:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "invites", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/invites/leaderboard": { "get": { "operationId": "invitesLeaderboard", "summary": "Invites leaderboard", "description": "`period=all` ranks by invites (verified + bonus), `period=season` by the active season’s invites (empty without a season). Pass `cursor=` for the next page.", "tags": [ "invites" ], "security": [ { "apiKey": [ "invites:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "season" ], "default": "all" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "all", "season" ] }, "season": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "startsAt": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "name", "startsAt", "endsAt" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "userId": { "type": "string" }, "score": { "type": "integer" }, "invites": { "type": "integer" }, "verified": { "type": "integer" }, "bonus": { "type": "integer" } }, "required": [ "rank", "userId", "score", "invites", "verified", "bonus" ] } }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "period", "season", "items", "total", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "invites.leaderboard", "x-botgg-scope": "invites:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "invites", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/invites/members/{userId}/bonus": { "post": { "operationId": "invitesAddBonus", "summary": "Add or remove bonus invites", "description": "Same as /invites add|remove. Counts toward the active season; milestone rewards for additions are granted by the bot within a minute. Written to the audit log.", "tags": [ "invites" ], "security": [ { "apiKey": [ "invites:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -100000, "maximum": 100000, "description": "Positive = add bonus invites, negative = remove" }, "reason": { "type": [ "string", "null" ], "maxLength": 200, "description": "Shown in the audit log" } }, "required": [ "amount" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "amount": { "type": "integer" }, "previousBonus": { "type": "integer" }, "bonus": { "type": "integer" }, "invites": { "type": "integer" }, "verified": { "type": "integer" } }, "required": [ "userId", "amount", "previousBonus", "bonus", "invites", "verified" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.\n`BOT_ACCOUNT` — Bots can’t hold a balance.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } }, "BOT_ACCOUNT": { "value": { "error": "BOT_ACCOUNT", "message": "Bots can’t hold a balance." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "invites.addBonus", "x-botgg-scope": "invites:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "invites", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/tickets": { "get": { "operationId": "ticketsList", "summary": "List tickets", "description": "Newest first. `status=active` = open + pending. Pass `before=` for the next page.", "tags": [ "tickets" ], "security": [ { "apiKey": [ "tickets:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "pending", "closed", "active" ] } }, { "name": "panelId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "userId", "in": "query", "required": false, "description": "Only tickets opened by this user", "schema": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Only tickets opened by this user" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "ticketNo": { "type": "integer" }, "status": { "type": "string", "enum": [ "open", "pending", "closed" ] }, "userId": { "type": "string", "description": "The opener" }, "panelId": { "type": [ "integer", "null" ] }, "subject": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "enum": [ "panel", "command", "context_menu", "dashboard", null ] }, "isThread": { "type": "boolean" }, "channelId": { "type": [ "string", "null" ] }, "claimedBy": { "type": [ "string", "null" ] }, "openedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "lastMessageAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "closedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "closedBy": { "type": [ "string", "null" ], "description": "null = closed by the bot (autoclose, API, …)" }, "closeReason": { "type": [ "string", "null" ] }, "closeType": { "type": [ "string", "null" ], "enum": [ "manual", "autoclose", "user_leave", "request", "channel_deleted", "thread_archived", null ] }, "messageCount": { "type": "object", "properties": { "user": { "type": "integer" }, "staff": { "type": "integer" } }, "required": [ "user", "staff" ] }, "rating": { "type": [ "integer", "null" ] }, "hasTranscript": { "type": "boolean" } }, "required": [ "ticketNo", "status", "userId", "panelId", "subject", "source", "isThread", "channelId", "claimedBy", "openedAt", "lastMessageAt", "closedAt", "closedBy", "closeReason", "closeType", "messageCount", "rating", "hasTranscript" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "tickets.list", "x-botgg-scope": "tickets:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "tickets", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/tickets/{ticketNo}": { "get": { "operationId": "ticketsGet", "summary": "Get a ticket", "description": "Includes the form answers, added members and a pending close request.", "tags": [ "tickets" ], "security": [ { "apiKey": [ "tickets:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "ticketNo", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketNo": { "type": "integer" }, "status": { "type": "string", "enum": [ "open", "pending", "closed" ] }, "userId": { "type": "string", "description": "The opener" }, "panelId": { "type": [ "integer", "null" ] }, "subject": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "enum": [ "panel", "command", "context_menu", "dashboard", null ] }, "isThread": { "type": "boolean" }, "channelId": { "type": [ "string", "null" ] }, "claimedBy": { "type": [ "string", "null" ] }, "openedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "lastMessageAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "closedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "closedBy": { "type": [ "string", "null" ], "description": "null = closed by the bot (autoclose, API, …)" }, "closeReason": { "type": [ "string", "null" ] }, "closeType": { "type": [ "string", "null" ], "enum": [ "manual", "autoclose", "user_leave", "request", "channel_deleted", "thread_archived", null ] }, "messageCount": { "type": "object", "properties": { "user": { "type": "integer" }, "staff": { "type": "integer" } }, "required": [ "user", "staff" ] }, "rating": { "type": [ "integer", "null" ] }, "hasTranscript": { "type": "boolean" }, "panelTitle": { "type": [ "string", "null" ] }, "firstResponseAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "firstResponseBy": { "type": [ "string", "null" ] }, "answers": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "fieldId", "label", "value" ] }, "description": "Form answers given when opening" }, "members": { "type": "array", "items": { "type": "object", "properties": { "targetId": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "role" ] } }, "required": [ "targetId", "type" ] }, "description": "Users / roles added to the ticket" }, "closeRequest": { "type": [ "object", "null" ], "properties": { "reason": { "type": [ "string", "null" ] }, "closeAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "viaApi": { "type": "boolean" } }, "required": [ "reason", "closeAt", "viaApi" ] } }, "required": [ "ticketNo", "status", "userId", "panelId", "subject", "source", "isThread", "channelId", "claimedBy", "openedAt", "lastMessageAt", "closedAt", "closedBy", "closeReason", "closeType", "messageCount", "rating", "hasTranscript", "panelTitle", "firstResponseAt", "firstResponseBy", "answers", "members", "closeRequest" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`TICKET_NOT_FOUND` — No ticket with this number on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "TICKET_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "TICKET_NOT_FOUND": { "value": { "error": "TICKET_NOT_FOUND", "message": "No ticket with this number on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "tickets.get", "x-botgg-scope": "tickets:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "tickets", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "TICKET_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/tickets/{ticketNo}/transcript": { "get": { "operationId": "ticketsTranscript", "summary": "Get a closed ticket’s transcript", "description": "The messages saved when the ticket was closed, oldest first, as text: no avatars and no attachment links (only file name, size and type). Pass `after=` for the next page. 404 TRANSCRIPT_NOT_FOUND for open tickets or when transcripts are off.", "tags": [ "tickets" ], "security": [ { "apiKey": [ "tickets:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "ticketNo", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "after", "in": "query", "required": false, "description": "A message id from `nextCursor`", "schema": { "type": "string", "pattern": "^\\d{17,20}$", "description": "A message id from `nextCursor`" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketNo": { "type": "integer" }, "generatedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "messageContent": { "type": "boolean", "description": "false: the bot ran without the Message Content intent, so other users’ text may be empty" }, "totalMessages": { "type": "integer" }, "users": { "type": "object", "additionalProperties": { "type": "object", "properties": { "username": { "type": [ "string", "null" ] }, "globalName": { "type": [ "string", "null" ] }, "bot": { "type": "boolean" }, "staff": { "type": "boolean" } }, "required": [ "username", "globalName", "bot", "staff" ] } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "authorId": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "editedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "system": { "type": "boolean" }, "replyTo": { "type": [ "string", "null" ] }, "embeds": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } }, "required": [ "title", "description", "fields" ] } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "contentType": { "type": [ "string", "null" ] } }, "required": [ "name", "size", "contentType" ] } }, "stickers": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "authorId", "content", "createdAt", "editedAt", "system", "replyTo", "embeds", "attachments", "stickers" ] } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page" } }, "required": [ "ticketNo", "generatedAt", "messageContent", "totalMessages", "users", "messages", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`TICKET_NOT_FOUND` — No ticket with this number on the server.\n`TRANSCRIPT_NOT_FOUND` — The ticket has no saved transcript (still open, transcripts off, or deleted).\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "TICKET_NOT_FOUND", "TRANSCRIPT_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "TICKET_NOT_FOUND": { "value": { "error": "TICKET_NOT_FOUND", "message": "No ticket with this number on the server." } }, "TRANSCRIPT_NOT_FOUND": { "value": { "error": "TRANSCRIPT_NOT_FOUND", "message": "The ticket has no saved transcript." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "tickets.transcript", "x-botgg-scope": "tickets:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "tickets", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "TICKET_NOT_FOUND", "TRANSCRIPT_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/tickets/{ticketNo}/close": { "post": { "operationId": "ticketsClose", "summary": "Close a ticket", "description": "The bot closes it within about a minute exactly like a staff close: transcript (if enabled for the panel), transcript-channel log, DM to the opener, channel deleted / thread archived. The reason is shown as \" (via API: )\". Written to the audit log.", "tags": [ "tickets" ], "security": [ { "apiKey": [ "tickets:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "ticketNo", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 500, "description": "Shown in the close log and the opener’s DM" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketNo": { "type": "integer" }, "status": { "const": "closing", "type": "string" }, "reason": { "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "ticketNo", "status", "reason", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`TICKET_NOT_FOUND` — No ticket with this number on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "TICKET_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "TICKET_NOT_FOUND": { "value": { "error": "TICKET_NOT_FOUND", "message": "No ticket with this number on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`TICKET_CLOSED` — The ticket is already closed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "TICKET_CLOSED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "TICKET_CLOSED": { "value": { "error": "TICKET_CLOSED", "message": "The ticket is already closed." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "tickets.close", "x-botgg-scope": "tickets:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "tickets", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "TICKET_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "TICKET_CLOSED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/applications/forms": { "get": { "operationId": "applicationsListForms", "summary": "List application forms", "description": "In the console’s order, with their questions and submission counts.", "tags": [ "applications" ], "security": [ { "apiKey": [ "applications:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "open": { "type": "boolean", "description": "The open toggle (the open window is in opensAt / closesAt)" }, "opensAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "closesAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "id", "type", "label", "required" ] } }, "submissions": { "type": "object", "properties": { "total": { "type": "integer" }, "open": { "type": "integer" } }, "required": [ "total", "open" ] } }, "required": [ "id", "title", "description", "open", "opensAt", "closesAt", "questions", "submissions" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "applications.listForms", "x-botgg-scope": "applications:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "applications", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/applications/submissions": { "get": { "operationId": "applicationsListSubmissions", "summary": "List applications", "description": "Newest first, without answers. `status=open` = pending + interview + hold, `decided` = accepted + denied. Pass `before=` for the next page.", "tags": [ "applications" ], "security": [ { "apiKey": [ "applications:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "interview", "hold", "accepted", "denied", "withdrawn", "open", "decided" ] } }, { "name": "formId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "userId", "in": "query", "required": false, "description": "Only this applicant", "schema": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Only this applicant" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "formId": { "type": [ "integer", "null" ], "description": "null when the form was deleted" }, "formTitle": { "type": [ "string", "null" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "interview", "hold", "accepted", "denied", "withdrawn" ] }, "votes": { "type": "object", "properties": { "up": { "type": "integer" }, "down": { "type": "integer" } }, "required": [ "up", "down" ] }, "submittedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "decidedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "decidedBy": { "type": [ "string", "null" ], "description": "null = system / API" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "number", "formId", "formTitle", "userId", "status", "votes", "submittedAt", "decidedAt", "decidedBy", "reason" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "applications.listSubmissions", "x-botgg-scope": "applications:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "applications", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/applications/submissions/{number}": { "get": { "operationId": "applicationsGetSubmission", "summary": "Get an application", "description": "With the answers and the applicant snapshot taken at submit time (account age, join date, roles, level).", "tags": [ "applications" ], "security": [ { "apiKey": [ "applications:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer" }, "formId": { "type": [ "integer", "null" ], "description": "null when the form was deleted" }, "formTitle": { "type": [ "string", "null" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "interview", "hold", "accepted", "denied", "withdrawn" ] }, "votes": { "type": "object", "properties": { "up": { "type": "integer" }, "down": { "type": "integer" } }, "required": [ "up", "down" ] }, "submittedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "decidedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "decidedBy": { "type": [ "string", "null" ], "description": "null = system / API" }, "reason": { "type": [ "string", "null" ] }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "text": { "type": "string" } }, "required": [ "id", "type", "label", "text" ] } }, "applicant": { "type": "object", "properties": { "accountCreatedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "joinedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "roleIds": { "type": "array", "items": { "type": "string" } }, "level": { "type": [ "integer", "null" ] } }, "required": [ "accountCreatedAt", "joinedAt", "roleIds", "level" ] }, "applying": { "type": "boolean", "description": "A console/API decision is still being applied in Discord" }, "failedActions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "error": { "type": [ "string", "null" ] } }, "required": [ "type", "error" ] } } }, "required": [ "number", "formId", "formTitle", "userId", "status", "votes", "submittedAt", "decidedAt", "decidedBy", "reason", "answers", "applicant", "applying", "failedActions" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`APPLICATION_NOT_FOUND` — No application (or form) with this number / id on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "APPLICATION_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "APPLICATION_NOT_FOUND": { "value": { "error": "APPLICATION_NOT_FOUND", "message": "No application (or form) with this number / id on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "applications.getSubmission", "x-botgg-scope": "applications:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "applications", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "APPLICATION_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/applications/submissions/{number}/decision": { "post": { "operationId": "applicationsDecide", "summary": "Accept or deny an application", "description": "Same as Accept / Deny in the console: decided now (status, reason, reapply cooldown after a denial), then the bot gives / removes the form’s roles, DMs the applicant, announces and updates the review within a few seconds (`applying`). Written to the audit log.", "tags": [ "applications" ], "security": [ { "apiKey": [ "applications:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "accepted", "denied" ] }, "reason": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Sent to the applicant (DM) and shown in the review" } }, "required": [ "decision" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer" }, "formId": { "type": [ "integer", "null" ], "description": "null when the form was deleted" }, "formTitle": { "type": [ "string", "null" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "interview", "hold", "accepted", "denied", "withdrawn" ] }, "votes": { "type": "object", "properties": { "up": { "type": "integer" }, "down": { "type": "integer" } }, "required": [ "up", "down" ] }, "submittedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "decidedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "decidedBy": { "type": [ "string", "null" ], "description": "null = system / API" }, "reason": { "type": [ "string", "null" ] }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "text": { "type": "string" } }, "required": [ "id", "type", "label", "text" ] } }, "applicant": { "type": "object", "properties": { "accountCreatedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "joinedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "roleIds": { "type": "array", "items": { "type": "string" } }, "level": { "type": [ "integer", "null" ] } }, "required": [ "accountCreatedAt", "joinedAt", "roleIds", "level" ] }, "applying": { "type": "boolean", "description": "A console/API decision is still being applied in Discord" }, "failedActions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "error": { "type": [ "string", "null" ] } }, "required": [ "type", "error" ] } } }, "required": [ "number", "formId", "formTitle", "userId", "status", "votes", "submittedAt", "decidedAt", "decidedBy", "reason", "answers", "applicant", "applying", "failedActions" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`SELF_DECISION` — The API key’s creator can’t decide their own application or appeal.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "SELF_DECISION" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "SELF_DECISION": { "value": { "error": "SELF_DECISION", "message": "The API key’s creator can’t decide their own application or appeal." } } } } } }, "404": { "description": "`APPLICATION_NOT_FOUND` — No application (or form) with this number / id on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "APPLICATION_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "APPLICATION_NOT_FOUND": { "value": { "error": "APPLICATION_NOT_FOUND", "message": "No application (or form) with this number / id on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`ALREADY_DECIDED` — The application or appeal was already decided (`status`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "ALREADY_DECIDED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "ALREADY_DECIDED": { "value": { "error": "ALREADY_DECIDED", "message": "The application or appeal was already decided." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "applications.decide", "x-botgg-scope": "applications:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "applications", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "SELF_DECISION", "APPLICATION_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "ALREADY_DECIDED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/appeals": { "get": { "operationId": "appealsList", "summary": "List ban appeals", "description": "Newest first. `status=open` (default) = open + waiting for the user’s answer; `all` = every status. Pass `before=` for the next page.", "tags": [ "appeals" ], "security": [ { "apiKey": [ "appeals:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "question", "approved", "rejected", "closed", "all" ], "default": "open" } }, { "name": "userId", "in": "query", "required": false, "description": "Only this user’s appeals", "schema": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Only this user’s appeals" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "userId": { "type": "string" }, "userTag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "question", "approved", "rejected", "closed" ] }, "banCaseNumber": { "type": [ "integer", "null" ] }, "claimedBy": { "type": [ "string", "null" ] }, "decidedBy": { "type": [ "string", "null" ], "description": "null = system / API" }, "decidedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "number", "userId", "userTag", "status", "banCaseNumber", "claimedBy", "decidedBy", "decidedAt", "reason", "createdAt", "lastActivityAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "appeals.list", "x-botgg-scope": "appeals:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "appeals", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/appeals/{number}": { "get": { "operationId": "appealsGet", "summary": "Get a ban appeal", "description": "With the answers, the ban reason and the conversation the appellant sees. Internal staff notes are never returned.", "tags": [ "appeals" ], "security": [ { "apiKey": [ "appeals:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer" }, "userId": { "type": "string" }, "userTag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "question", "approved", "rejected", "closed" ] }, "banCaseNumber": { "type": [ "integer", "null" ] }, "claimedBy": { "type": [ "string", "null" ] }, "decidedBy": { "type": [ "string", "null" ], "description": "null = system / API" }, "decidedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "banReason": { "type": [ "string", "null" ] }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "value": {} }, "required": [ "id", "type", "label", "value" ] } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": "string", "enum": [ "user", "staff" ] }, "authorId": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "author", "authorId", "text", "createdAt" ] }, "description": "The conversation the appellant sees (staff questions + replies). Internal notes are never included." }, "applying": { "type": "boolean", "description": "A console/API decision is still being applied in Discord" }, "failedAction": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "error": { "type": [ "string", "null" ] } }, "required": [ "type", "error" ] } }, "required": [ "number", "userId", "userTag", "status", "banCaseNumber", "claimedBy", "decidedBy", "decidedAt", "reason", "createdAt", "lastActivityAt", "banReason", "answers", "messages", "applying", "failedAction" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`APPEAL_NOT_FOUND` — No ban appeal with this number on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "APPEAL_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "APPEAL_NOT_FOUND": { "value": { "error": "APPEAL_NOT_FOUND", "message": "No ban appeal with this number on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "appeals.get", "x-botgg-scope": "appeals:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "appeals", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "APPEAL_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/appeals/{number}/approve": { "post": { "operationId": "appealsApprove", "summary": "Approve a ban appeal (unban)", "description": "Same as Approve in the console: the bot unbans within a few seconds (an `unban` moderation case when Moderation is enabled), creates a single-use invite and DMs the user per the appeal settings. Written to the audit log.", "tags": [ "appeals" ], "security": [ { "apiKey": [ "appeals:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Sent to the appellant (DM / appeal page)" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer" }, "userId": { "type": "string" }, "userTag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "question", "approved", "rejected", "closed" ] }, "banCaseNumber": { "type": [ "integer", "null" ] }, "claimedBy": { "type": [ "string", "null" ] }, "decidedBy": { "type": [ "string", "null" ], "description": "null = system / API" }, "decidedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "banReason": { "type": [ "string", "null" ] }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "value": {} }, "required": [ "id", "type", "label", "value" ] } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": "string", "enum": [ "user", "staff" ] }, "authorId": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "author", "authorId", "text", "createdAt" ] }, "description": "The conversation the appellant sees (staff questions + replies). Internal notes are never included." }, "applying": { "type": "boolean", "description": "A console/API decision is still being applied in Discord" }, "failedAction": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "error": { "type": [ "string", "null" ] } }, "required": [ "type", "error" ] } }, "required": [ "number", "userId", "userTag", "status", "banCaseNumber", "claimedBy", "decidedBy", "decidedAt", "reason", "createdAt", "lastActivityAt", "banReason", "answers", "messages", "applying", "failedAction" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`SELF_DECISION` — The API key’s creator can’t decide their own application or appeal.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "SELF_DECISION" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "SELF_DECISION": { "value": { "error": "SELF_DECISION", "message": "The API key’s creator can’t decide their own application or appeal." } } } } } }, "404": { "description": "`APPEAL_NOT_FOUND` — No ban appeal with this number on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "APPEAL_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "APPEAL_NOT_FOUND": { "value": { "error": "APPEAL_NOT_FOUND", "message": "No ban appeal with this number on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`ALREADY_DECIDED` — The application or appeal was already decided (`status`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "ALREADY_DECIDED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "ALREADY_DECIDED": { "value": { "error": "ALREADY_DECIDED", "message": "The application or appeal was already decided." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "appeals.approve", "x-botgg-scope": "appeals:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "appeals", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "SELF_DECISION", "APPEAL_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "ALREADY_DECIDED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/appeals/{number}/reject": { "post": { "operationId": "appealsReject", "summary": "Reject a ban appeal", "description": "Same as Reject in the console: the user gets the rejection DM per the appeal settings and the re-appeal cooldown starts. Written to the audit log.", "tags": [ "appeals" ], "security": [ { "apiKey": [ "appeals:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Sent to the appellant (DM / appeal page)" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer" }, "userId": { "type": "string" }, "userTag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "question", "approved", "rejected", "closed" ] }, "banCaseNumber": { "type": [ "integer", "null" ] }, "claimedBy": { "type": [ "string", "null" ] }, "decidedBy": { "type": [ "string", "null" ], "description": "null = system / API" }, "decidedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "banReason": { "type": [ "string", "null" ] }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "value": {} }, "required": [ "id", "type", "label", "value" ] } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": "string", "enum": [ "user", "staff" ] }, "authorId": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "author", "authorId", "text", "createdAt" ] }, "description": "The conversation the appellant sees (staff questions + replies). Internal notes are never included." }, "applying": { "type": "boolean", "description": "A console/API decision is still being applied in Discord" }, "failedAction": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "error": { "type": [ "string", "null" ] } }, "required": [ "type", "error" ] } }, "required": [ "number", "userId", "userTag", "status", "banCaseNumber", "claimedBy", "decidedBy", "decidedAt", "reason", "createdAt", "lastActivityAt", "banReason", "answers", "messages", "applying", "failedAction" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`SELF_DECISION` — The API key’s creator can’t decide their own application or appeal.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "SELF_DECISION" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "SELF_DECISION": { "value": { "error": "SELF_DECISION", "message": "The API key’s creator can’t decide their own application or appeal." } } } } } }, "404": { "description": "`APPEAL_NOT_FOUND` — No ban appeal with this number on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "APPEAL_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "APPEAL_NOT_FOUND": { "value": { "error": "APPEAL_NOT_FOUND", "message": "No ban appeal with this number on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`ALREADY_DECIDED` — The application or appeal was already decided (`status`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "ALREADY_DECIDED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "ALREADY_DECIDED": { "value": { "error": "ALREADY_DECIDED", "message": "The application or appeal was already decided." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "appeals.reject", "x-botgg-scope": "appeals:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "appeals", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "SELF_DECISION", "APPEAL_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "ALREADY_DECIDED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/cases": { "get": { "operationId": "moderationListCases", "summary": "List moderation cases", "description": "Newest first (deleted cases are left out). Pass `before=` for the next page.", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "tempban", "softban", "unban", "note", "purge" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "command", "automod", "escalation", "antiraid", "antinuke", "console", "api" ] } }, { "name": "userId", "in": "query", "required": false, "description": "Only cases against this user", "schema": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Only cases against this user" } }, { "name": "moderatorId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "active", "in": "query", "required": false, "description": "1 = only running warnings / timeouts / tempbans", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ], "description": "1 = only running warnings / timeouts / tempbans" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "tempban", "softban", "unban", "note", "purge" ] }, "userId": { "type": "string", "description": "The target" }, "userTag": { "type": [ "string", "null" ] }, "moderatorId": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "integer", "null" ] }, "evidence": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "command", "automod", "escalation", "antiraid", "antinuke", "console", "api" ] }, "active": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "dmStatus": { "type": [ "string", "null" ], "enum": [ "sent", "failed", "off", null ] }, "apiKey": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "description": "Set when the action was made with an API key" }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "number", "action", "userId", "userTag", "moderatorId", "reason", "durationSeconds", "evidence", "source", "active", "expiresAt", "resolvedAt", "dmStatus", "apiKey", "createdAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.listCases", "x-botgg-scope": "moderation:read", "x-botgg-sensitive": true, "x-botgg-access": "read", "x-botgg-feature": "moderation", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/cases/{number}": { "get": { "operationId": "moderationGetCase", "summary": "Get a moderation case", "description": "With its timeline (created, reason / evidence edits, DM, expired, revoked, escalated).", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "tempban", "softban", "unban", "note", "purge" ] }, "userId": { "type": "string", "description": "The target" }, "userTag": { "type": [ "string", "null" ] }, "moderatorId": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "integer", "null" ] }, "evidence": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "command", "automod", "escalation", "antiraid", "antinuke", "console", "api" ] }, "active": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "dmStatus": { "type": [ "string", "null" ], "enum": [ "sent", "failed", "off", null ] }, "apiKey": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "description": "Set when the action was made with an API key" }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "actorId": { "type": [ "string", "null" ] }, "data": {}, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "type", "actorId", "data", "createdAt" ] } } }, "required": [ "number", "action", "userId", "userTag", "moderatorId", "reason", "durationSeconds", "evidence", "source", "active", "expiresAt", "resolvedAt", "dmStatus", "apiKey", "createdAt", "events" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`CASE_NOT_FOUND` — No moderation case with this number on the server.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "CASE_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "CASE_NOT_FOUND": { "value": { "error": "CASE_NOT_FOUND", "message": "No moderation case with this number on the server." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.getCase", "x-botgg-scope": "moderation:read", "x-botgg-sensitive": true, "x-botgg-access": "read", "x-botgg-feature": "moderation", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "CASE_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/users/{userId}/warn": { "post": { "operationId": "moderationWarn", "summary": "Warn a member", "description": "Same as /warn: a warning case (counts toward escalation), DM per the Moderation settings. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required. Shown in the case, the mod log and the member’s DM" }, "evidence": { "type": "array", "items": { "type": "string", "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$" }, "maxItems": 5, "description": "Up to 5 links" } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "unban" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "caseNumber": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)" }, "requestedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "actionId", "action", "userId", "status", "caseNumber", "error", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`MODERATOR_NOT_MEMBER` — The API key’s creator is no longer a member of the server (moderation acts in their name).\n`MODERATOR_MISSING_PERMISSION` — The API key’s creator lacks the Discord permission for this action (`required`).\n`HIERARCHY` — The target can’t be moderated (`reason`: self = the key’s creator, bot, owner, higher = not below the creator’s highest role, botHigher = not below the bot’s).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "MODERATOR_NOT_MEMBER": { "value": { "error": "MODERATOR_NOT_MEMBER", "message": "The API key’s creator is no longer a member of the server." } }, "MODERATOR_MISSING_PERMISSION": { "value": { "error": "MODERATOR_MISSING_PERMISSION", "message": "The API key’s creator lacks the Discord permission for this action." } }, "HIERARCHY": { "value": { "error": "HIERARCHY", "message": "The target can’t be moderated." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`NOT_BANNED` — The user is not banned from the server.\n`BOT_MISSING_PERMISSIONS` — The bot lacks the Discord permission for this action (`missing`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "NOT_BANNED": { "value": { "error": "NOT_BANNED", "message": "The user is not banned from the server." } }, "BOT_MISSING_PERMISSIONS": { "value": { "error": "BOT_MISSING_PERMISSIONS", "message": "The bot lacks the Discord permission for this action." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.warn", "x-botgg-scope": "moderation:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "moderation", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/users/{userId}/timeout": { "post": { "operationId": "moderationTimeout", "summary": "Time out a member", "description": "Same as /timeout: Discord timeout for `durationSeconds`, a case, DM per the settings. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required. Shown in the case, the mod log and the member’s DM" }, "durationSeconds": { "type": "integer", "minimum": 60, "maximum": 2419200, "description": "1 minute to 28 days" }, "evidence": { "type": "array", "items": { "type": "string", "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$" }, "maxItems": 5, "description": "Up to 5 links" } }, "required": [ "reason", "durationSeconds" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "unban" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "caseNumber": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)" }, "requestedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "actionId", "action", "userId", "status", "caseNumber", "error", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`MODERATOR_NOT_MEMBER` — The API key’s creator is no longer a member of the server (moderation acts in their name).\n`MODERATOR_MISSING_PERMISSION` — The API key’s creator lacks the Discord permission for this action (`required`).\n`HIERARCHY` — The target can’t be moderated (`reason`: self = the key’s creator, bot, owner, higher = not below the creator’s highest role, botHigher = not below the bot’s).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "MODERATOR_NOT_MEMBER": { "value": { "error": "MODERATOR_NOT_MEMBER", "message": "The API key’s creator is no longer a member of the server." } }, "MODERATOR_MISSING_PERMISSION": { "value": { "error": "MODERATOR_MISSING_PERMISSION", "message": "The API key’s creator lacks the Discord permission for this action." } }, "HIERARCHY": { "value": { "error": "HIERARCHY", "message": "The target can’t be moderated." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`NOT_BANNED` — The user is not banned from the server.\n`BOT_MISSING_PERMISSIONS` — The bot lacks the Discord permission for this action (`missing`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "NOT_BANNED": { "value": { "error": "NOT_BANNED", "message": "The user is not banned from the server." } }, "BOT_MISSING_PERMISSIONS": { "value": { "error": "BOT_MISSING_PERMISSIONS", "message": "The bot lacks the Discord permission for this action." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.timeout", "x-botgg-scope": "moderation:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "moderation", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/users/{userId}/untimeout": { "post": { "operationId": "moderationUntimeout", "summary": "Remove a member’s timeout", "description": "Same as /untimeout. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required. Shown in the case, the mod log and the member’s DM" } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "unban" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "caseNumber": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)" }, "requestedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "actionId", "action", "userId", "status", "caseNumber", "error", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`MODERATOR_NOT_MEMBER` — The API key’s creator is no longer a member of the server (moderation acts in their name).\n`MODERATOR_MISSING_PERMISSION` — The API key’s creator lacks the Discord permission for this action (`required`).\n`HIERARCHY` — The target can’t be moderated (`reason`: self = the key’s creator, bot, owner, higher = not below the creator’s highest role, botHigher = not below the bot’s).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "MODERATOR_NOT_MEMBER": { "value": { "error": "MODERATOR_NOT_MEMBER", "message": "The API key’s creator is no longer a member of the server." } }, "MODERATOR_MISSING_PERMISSION": { "value": { "error": "MODERATOR_MISSING_PERMISSION", "message": "The API key’s creator lacks the Discord permission for this action." } }, "HIERARCHY": { "value": { "error": "HIERARCHY", "message": "The target can’t be moderated." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`NOT_BANNED` — The user is not banned from the server.\n`BOT_MISSING_PERMISSIONS` — The bot lacks the Discord permission for this action (`missing`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "NOT_BANNED": { "value": { "error": "NOT_BANNED", "message": "The user is not banned from the server." } }, "BOT_MISSING_PERMISSIONS": { "value": { "error": "BOT_MISSING_PERMISSIONS", "message": "The bot lacks the Discord permission for this action." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.untimeout", "x-botgg-scope": "moderation:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "moderation", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/users/{userId}/kick": { "post": { "operationId": "moderationKick", "summary": "Kick a member", "description": "Same as /kick: DM (before the kick) per the settings, then the kick and a case. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required. Shown in the case, the mod log and the member’s DM" }, "evidence": { "type": "array", "items": { "type": "string", "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$" }, "maxItems": 5, "description": "Up to 5 links" } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "unban" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "caseNumber": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)" }, "requestedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "actionId", "action", "userId", "status", "caseNumber", "error", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`MODERATOR_NOT_MEMBER` — The API key’s creator is no longer a member of the server (moderation acts in their name).\n`MODERATOR_MISSING_PERMISSION` — The API key’s creator lacks the Discord permission for this action (`required`).\n`HIERARCHY` — The target can’t be moderated (`reason`: self = the key’s creator, bot, owner, higher = not below the creator’s highest role, botHigher = not below the bot’s).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "MODERATOR_NOT_MEMBER": { "value": { "error": "MODERATOR_NOT_MEMBER", "message": "The API key’s creator is no longer a member of the server." } }, "MODERATOR_MISSING_PERMISSION": { "value": { "error": "MODERATOR_MISSING_PERMISSION", "message": "The API key’s creator lacks the Discord permission for this action." } }, "HIERARCHY": { "value": { "error": "HIERARCHY", "message": "The target can’t be moderated." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`NOT_BANNED` — The user is not banned from the server.\n`BOT_MISSING_PERMISSIONS` — The bot lacks the Discord permission for this action (`missing`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "NOT_BANNED": { "value": { "error": "NOT_BANNED", "message": "The user is not banned from the server." } }, "BOT_MISSING_PERMISSIONS": { "value": { "error": "BOT_MISSING_PERMISSIONS", "message": "The bot lacks the Discord permission for this action." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.kick", "x-botgg-scope": "moderation:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "moderation", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/users/{userId}/ban": { "post": { "operationId": "moderationBan", "summary": "Ban a user", "description": "Same as /ban: with `durationSeconds` a temporary ban the bot lifts automatically; `deleteMessageSeconds` deletes recent messages. Works for users who already left. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required. Shown in the case, the mod log and the member’s DM" }, "deleteMessageSeconds": { "type": "integer", "minimum": 0, "maximum": 604800, "description": "Delete the user’s messages of the last N seconds (≤ 7 days)" }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 31536000, "description": "Temporary ban (≤ 365 days); omit for a permanent ban" }, "evidence": { "type": "array", "items": { "type": "string", "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$" }, "maxItems": 5, "description": "Up to 5 links" } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "unban" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "caseNumber": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)" }, "requestedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "actionId", "action", "userId", "status", "caseNumber", "error", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`MODERATOR_NOT_MEMBER` — The API key’s creator is no longer a member of the server (moderation acts in their name).\n`MODERATOR_MISSING_PERMISSION` — The API key’s creator lacks the Discord permission for this action (`required`).\n`HIERARCHY` — The target can’t be moderated (`reason`: self = the key’s creator, bot, owner, higher = not below the creator’s highest role, botHigher = not below the bot’s).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "MODERATOR_NOT_MEMBER": { "value": { "error": "MODERATOR_NOT_MEMBER", "message": "The API key’s creator is no longer a member of the server." } }, "MODERATOR_MISSING_PERMISSION": { "value": { "error": "MODERATOR_MISSING_PERMISSION", "message": "The API key’s creator lacks the Discord permission for this action." } }, "HIERARCHY": { "value": { "error": "HIERARCHY", "message": "The target can’t be moderated." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`NOT_BANNED` — The user is not banned from the server.\n`BOT_MISSING_PERMISSIONS` — The bot lacks the Discord permission for this action (`missing`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "NOT_BANNED": { "value": { "error": "NOT_BANNED", "message": "The user is not banned from the server." } }, "BOT_MISSING_PERMISSIONS": { "value": { "error": "BOT_MISSING_PERMISSIONS", "message": "The bot lacks the Discord permission for this action." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.ban", "x-botgg-scope": "moderation:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "moderation", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/users/{userId}/unban": { "post": { "operationId": "moderationUnban", "summary": "Unban a user", "description": "Same as /unban (ends a running tempban). 409 NOT_BANNED when the user isn’t banned. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required. Shown in the case, the mod log and the member’s DM" } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "unban" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "caseNumber": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)" }, "requestedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "actionId", "action", "userId", "status", "caseNumber", "error", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.\n`MODERATOR_NOT_MEMBER` — The API key’s creator is no longer a member of the server (moderation acts in their name).\n`MODERATOR_MISSING_PERMISSION` — The API key’s creator lacks the Discord permission for this action (`required`).\n`HIERARCHY` — The target can’t be moderated (`reason`: self = the key’s creator, bot, owner, higher = not below the creator’s highest role, botHigher = not below the bot’s).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } }, "MODERATOR_NOT_MEMBER": { "value": { "error": "MODERATOR_NOT_MEMBER", "message": "The API key’s creator is no longer a member of the server." } }, "MODERATOR_MISSING_PERMISSION": { "value": { "error": "MODERATOR_MISSING_PERMISSION", "message": "The API key’s creator lacks the Discord permission for this action." } }, "HIERARCHY": { "value": { "error": "HIERARCHY", "message": "The target can’t be moderated." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`NOT_BANNED` — The user is not banned from the server.\n`BOT_MISSING_PERMISSIONS` — The bot lacks the Discord permission for this action (`missing`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "NOT_BANNED": { "value": { "error": "NOT_BANNED", "message": "The user is not banned from the server." } }, "BOT_MISSING_PERMISSIONS": { "value": { "error": "BOT_MISSING_PERMISSIONS", "message": "The bot lacks the Discord permission for this action." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.unban", "x-botgg-scope": "moderation:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "moderation", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "FEATURE_DISABLED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/moderation/actions/{actionId}": { "get": { "operationId": "moderationGetAction", "summary": "Get the result of a moderation action", "description": "Only actions made with the same API key. `done` → `caseNumber`; `failed` → `error` (the bot re-checks everything right before acting).", "tags": [ "moderation" ], "security": [ { "apiKey": [ "moderation:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "action": { "type": "string", "enum": [ "warn", "timeout", "untimeout", "kick", "ban", "unban" ] }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "caseNumber": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)" }, "requestedAt": { "type": [ "string", "null" ], "description": "ISO 8601 date-time" } }, "required": [ "actionId", "action", "userId", "status", "caseNumber", "error", "requestedAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`MODERATION_ACTION_NOT_FOUND` — No moderation action with this id was made with this API key.\n`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "MODERATION_ACTION_NOT_FOUND", "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "MODERATION_ACTION_NOT_FOUND": { "value": { "error": "MODERATION_ACTION_NOT_FOUND", "message": "No moderation action with this id was made with this API key." } }, "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "moderation.getAction", "x-botgg-scope": "moderation:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "moderation", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "MODERATION_ACTION_NOT_FOUND", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/stores": { "get": { "operationId": "shopListStores", "summary": "List stores", "description": "The built-in Main store (`id: null`, items without a store) first, then the stores in their order.", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "null = the built-in Main store" }, "main": { "type": "boolean" }, "name": { "type": [ "string", "null" ], "description": "null for the Main store" }, "emoji": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "channelIds": { "type": "array", "items": { "type": "string" } }, "itemCount": { "type": "integer" } }, "required": [ "id", "main", "name", "emoji", "description", "color", "enabled", "channelIds", "itemCount" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.listStores", "x-botgg-scope": "shop:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "shop", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/items": { "get": { "operationId": "shopListItems", "summary": "List items", "description": "In sort order. Only enabled items unless `includeDisabled=true`; hidden items are included (`hidden: true`).", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "storeId", "in": "query", "required": false, "schema": { "anyOf": [ { "const": "main", "type": "string" }, { "type": "string", "pattern": "^\\d{1,12}$" } ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 32 } }, { "name": "includeDisabled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "storeId": { "type": [ "integer", "null" ], "description": "null = Main store" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "emoji": { "type": [ "string", "null" ] }, "price": { "type": "integer" }, "type": { "type": "string", "enum": [ "role", "color", "item" ] }, "category": { "type": [ "string", "null" ] }, "roleId": { "type": [ "string", "null" ] }, "durationSec": { "type": "integer", "description": "Timed role length; 0 = permanent" }, "consumable": { "type": "boolean" }, "fulfillment": { "type": "boolean", "description": "Staff deliver it (fulfilment request)" }, "stock": { "type": [ "integer", "null" ], "description": "null = unlimited" }, "perUserLimit": { "type": [ "integer", "null" ] }, "requiredRoleIds": { "type": "array", "items": { "type": "string" } }, "minLevel": { "type": "integer" }, "enabled": { "type": "boolean" }, "hidden": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "required": [ "id", "storeId", "name", "description", "emoji", "price", "type", "category", "roleId", "durationSec", "consumable", "fulfillment", "stock", "perUserLimit", "requiredRoleIds", "minLevel", "enabled", "hidden", "sortOrder" ] } }, "currency": { "type": "object", "properties": { "name": { "type": "string" }, "plural": { "type": "string" }, "emoji": { "type": [ "string", "null" ] } }, "required": [ "name", "plural", "emoji" ] } }, "required": [ "items", "currency" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.listItems", "x-botgg-scope": "shop:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "shop", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/items/{itemId}": { "get": { "operationId": "shopGetItem", "summary": "Get an item", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "storeId": { "type": [ "integer", "null" ], "description": "null = Main store" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "emoji": { "type": [ "string", "null" ] }, "price": { "type": "integer" }, "type": { "type": "string", "enum": [ "role", "color", "item" ] }, "category": { "type": [ "string", "null" ] }, "roleId": { "type": [ "string", "null" ] }, "durationSec": { "type": "integer", "description": "Timed role length; 0 = permanent" }, "consumable": { "type": "boolean" }, "fulfillment": { "type": "boolean", "description": "Staff deliver it (fulfilment request)" }, "stock": { "type": [ "integer", "null" ], "description": "null = unlimited" }, "perUserLimit": { "type": [ "integer", "null" ] }, "requiredRoleIds": { "type": "array", "items": { "type": "string" } }, "minLevel": { "type": "integer" }, "enabled": { "type": "boolean" }, "hidden": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "required": [ "id", "storeId", "name", "description", "emoji", "price", "type", "category", "roleId", "durationSec", "consumable", "fulfillment", "stock", "perUserLimit", "requiredRoleIds", "minLevel", "enabled", "hidden", "sortOrder" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`SHOP_ITEM_NOT_FOUND` — No Shop item with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "SHOP_ITEM_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "SHOP_ITEM_NOT_FOUND": { "value": { "error": "SHOP_ITEM_NOT_FOUND", "message": "No Shop item with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.getItem", "x-botgg-scope": "shop:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "shop", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "SHOP_ITEM_NOT_FOUND", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] }, "patch": { "operationId": "shopUpdateItem", "summary": "Restock or turn an item on/off", "description": "Like /shopadmin restock and toggle. Send `stock` (null = unlimited) and/or `enabled`.", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Off = not listed, not buyable" }, "stock": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000, "description": "New stock; null = unlimited" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "storeId": { "type": [ "integer", "null" ], "description": "null = Main store" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "emoji": { "type": [ "string", "null" ] }, "price": { "type": "integer" }, "type": { "type": "string", "enum": [ "role", "color", "item" ] }, "category": { "type": [ "string", "null" ] }, "roleId": { "type": [ "string", "null" ] }, "durationSec": { "type": "integer", "description": "Timed role length; 0 = permanent" }, "consumable": { "type": "boolean" }, "fulfillment": { "type": "boolean", "description": "Staff deliver it (fulfilment request)" }, "stock": { "type": [ "integer", "null" ], "description": "null = unlimited" }, "perUserLimit": { "type": [ "integer", "null" ] }, "requiredRoleIds": { "type": "array", "items": { "type": "string" } }, "minLevel": { "type": "integer" }, "enabled": { "type": "boolean" }, "hidden": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "required": [ "id", "storeId", "name", "description", "emoji", "price", "type", "category", "roleId", "durationSec", "consumable", "fulfillment", "stock", "perUserLimit", "requiredRoleIds", "minLevel", "enabled", "hidden", "sortOrder" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`SHOP_ITEM_NOT_FOUND` — No Shop item with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "SHOP_ITEM_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "SHOP_ITEM_NOT_FOUND": { "value": { "error": "SHOP_ITEM_NOT_FOUND", "message": "No Shop item with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.updateItem", "x-botgg-scope": "shop:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "shop", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "SHOP_ITEM_NOT_FOUND", "FEATURE_DISABLED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/members/{userId}/inventory": { "get": { "operationId": "shopGetInventory", "summary": "A member’s inventory", "description": "Non-refunded purchases (owned and used), newest first; `roleActive` = a granted role that hasn’t expired or been removed.", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "itemId": { "type": [ "integer", "null" ], "description": "null when the item was deleted (the snapshot stays)" }, "storeId": { "type": [ "integer", "null" ] }, "storeName": { "type": [ "string", "null" ] }, "itemName": { "type": "string" }, "itemEmoji": { "type": [ "string", "null" ] }, "itemType": { "type": "string" }, "userId": { "type": "string" }, "price": { "type": "integer", "description": "0 for free grants" }, "status": { "type": "string", "enum": [ "owned", "used", "refunded" ] }, "roleId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "roleRemovedAt": { "type": [ "string", "null" ] }, "fulfillment": { "type": "string", "enum": [ "none", "pending", "done" ] }, "bankTransactionId": { "type": [ "integer", "null" ] }, "refundTransactionId": { "type": [ "integer", "null" ] }, "usedAt": { "type": [ "string", "null" ] }, "refundedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "roleActive": { "type": "boolean" } }, "required": [ "id", "itemId", "storeId", "storeName", "itemName", "itemEmoji", "itemType", "userId", "price", "status", "roleId", "expiresAt", "roleRemovedAt", "fulfillment", "bankTransactionId", "refundTransactionId", "usedAt", "refundedAt", "createdAt", "roleActive" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.getInventory", "x-botgg-scope": "shop:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "shop", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/purchases": { "get": { "operationId": "shopListPurchases", "summary": "List purchases", "description": "The purchase ledger, newest first. Pass `before=` for the next page.", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "userId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "itemId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "storeId", "in": "query", "required": false, "schema": { "anyOf": [ { "const": "main", "type": "string" }, { "type": "string", "pattern": "^\\d{1,12}$" } ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "owned", "used", "refunded" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "itemId": { "type": [ "integer", "null" ], "description": "null when the item was deleted (the snapshot stays)" }, "storeId": { "type": [ "integer", "null" ] }, "storeName": { "type": [ "string", "null" ] }, "itemName": { "type": "string" }, "itemEmoji": { "type": [ "string", "null" ] }, "itemType": { "type": "string" }, "userId": { "type": "string" }, "price": { "type": "integer", "description": "0 for free grants" }, "status": { "type": "string", "enum": [ "owned", "used", "refunded" ] }, "roleId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "roleRemovedAt": { "type": [ "string", "null" ] }, "fulfillment": { "type": "string", "enum": [ "none", "pending", "done" ] }, "bankTransactionId": { "type": [ "integer", "null" ] }, "refundTransactionId": { "type": [ "integer", "null" ] }, "usedAt": { "type": [ "string", "null" ] }, "refundedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "itemId", "storeId", "storeName", "itemName", "itemEmoji", "itemType", "userId", "price", "status", "roleId", "expiresAt", "roleRemovedAt", "fulfillment", "bankTransactionId", "refundTransactionId", "usedAt", "refundedAt", "createdAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.listPurchases", "x-botgg-scope": "shop:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "shop", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/purchases/{purchaseId}": { "get": { "operationId": "shopGetPurchase", "summary": "Get a purchase", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "itemId": { "type": [ "integer", "null" ], "description": "null when the item was deleted (the snapshot stays)" }, "storeId": { "type": [ "integer", "null" ] }, "storeName": { "type": [ "string", "null" ] }, "itemName": { "type": "string" }, "itemEmoji": { "type": [ "string", "null" ] }, "itemType": { "type": "string" }, "userId": { "type": "string" }, "price": { "type": "integer", "description": "0 for free grants" }, "status": { "type": "string", "enum": [ "owned", "used", "refunded" ] }, "roleId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "roleRemovedAt": { "type": [ "string", "null" ] }, "fulfillment": { "type": "string", "enum": [ "none", "pending", "done" ] }, "bankTransactionId": { "type": [ "integer", "null" ] }, "refundTransactionId": { "type": [ "integer", "null" ] }, "usedAt": { "type": [ "string", "null" ] }, "refundedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "itemId", "storeId", "storeName", "itemName", "itemEmoji", "itemType", "userId", "price", "status", "roleId", "expiresAt", "roleRemovedAt", "fulfillment", "bankTransactionId", "refundTransactionId", "usedAt", "refundedAt", "createdAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`SHOP_PURCHASE_NOT_FOUND` — No purchase with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "SHOP_PURCHASE_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "SHOP_PURCHASE_NOT_FOUND": { "value": { "error": "SHOP_PURCHASE_NOT_FOUND", "message": "No purchase with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.getPurchase", "x-botgg-scope": "shop:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "shop", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "SHOP_PURCHASE_NOT_FOUND", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/members/{userId}/purchases": { "post": { "operationId": "shopPurchase", "summary": "Buy an item for a member", "description": "Same rules as /shop: the price is charged from the member’s Bank balance in one transaction with the stock and limits; requirements (roles, level) apply. A role item’s role is given right away (if Discord refuses, nothing is charged). Fulfilment requests and the Shop log are posted like a /shop purchase.", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "integer", "minimum": 1 }, "expectedPrice": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "Refused with SHOP_ITEM_UNAVAILABLE (price_changed) when the price differs" } }, "required": [ "itemId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "integer" }, "itemId": { "type": [ "integer", "null" ], "description": "null when the item was deleted (the snapshot stays)" }, "storeId": { "type": [ "integer", "null" ] }, "storeName": { "type": [ "string", "null" ] }, "itemName": { "type": "string" }, "itemEmoji": { "type": [ "string", "null" ] }, "itemType": { "type": "string" }, "userId": { "type": "string" }, "price": { "type": "integer", "description": "0 for free grants" }, "status": { "type": "string", "enum": [ "owned", "used", "refunded" ] }, "roleId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "roleRemovedAt": { "type": [ "string", "null" ] }, "fulfillment": { "type": "string", "enum": [ "none", "pending", "done" ] }, "bankTransactionId": { "type": [ "integer", "null" ] }, "refundTransactionId": { "type": [ "integer", "null" ] }, "usedAt": { "type": [ "string", "null" ] }, "refundedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "itemId", "storeId", "storeName", "itemName", "itemEmoji", "itemType", "userId", "price", "status", "roleId", "expiresAt", "roleRemovedAt", "fulfillment", "bankTransactionId", "refundTransactionId", "usedAt", "refundedAt", "createdAt" ] }, "balance": { "type": [ "integer", "null" ], "description": "The member’s balance afterwards (null when unchanged)" } }, "required": [ "purchase", "balance" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.\n`SHOP_ITEM_NOT_FOUND` — No Shop item with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "SHOP_ITEM_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } }, "SHOP_ITEM_NOT_FOUND": { "value": { "error": "SHOP_ITEM_NOT_FOUND", "message": "No Shop item with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`BANK_DISABLED` — The Bank feature is turned off on the server.\n`INSUFFICIENT_FUNDS` — A remove would make the balance negative (`balance`).\n`SHOP_ITEM_UNAVAILABLE` — The item can’t be bought or granted right now (`reason`: disabled, store_closed, out_of_stock, limit, price_changed, roles, level, already_has_role).\n`ROLE_NOT_GRANTABLE` — The bot can’t give the item’s role (role missing, above the bot, too powerful, or Discord refused). Nothing was charged.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "BANK_DISABLED", "INSUFFICIENT_FUNDS", "SHOP_ITEM_UNAVAILABLE", "ROLE_NOT_GRANTABLE" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "BANK_DISABLED": { "value": { "error": "BANK_DISABLED", "message": "The Bank feature is turned off on the server." } }, "INSUFFICIENT_FUNDS": { "value": { "error": "INSUFFICIENT_FUNDS", "message": "A remove would make the balance negative." } }, "SHOP_ITEM_UNAVAILABLE": { "value": { "error": "SHOP_ITEM_UNAVAILABLE", "message": "The item can’t be bought or granted right now." } }, "ROLE_NOT_GRANTABLE": { "value": { "error": "ROLE_NOT_GRANTABLE", "message": "The bot can’t give the item’s role (role missing, above the bot, too powerful, or Discord refused). Nothing was charged." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.\n`BOT_ACCOUNT` — Bots can’t hold a balance.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } }, "BOT_ACCOUNT": { "value": { "error": "BOT_ACCOUNT", "message": "Bots can’t hold a balance." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.purchase", "x-botgg-scope": "shop:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "shop", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "SHOP_ITEM_NOT_FOUND", "FEATURE_DISABLED", "BANK_DISABLED", "INSUFFICIENT_FUNDS", "SHOP_ITEM_UNAVAILABLE", "ROLE_NOT_GRANTABLE", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/members/{userId}/grants": { "post": { "operationId": "shopGrant", "summary": "Give an item to a member for free", "description": "A staff grant: recorded as a purchase with price 0, no Bank change. Ignores the item’s on/off switch, a closed store, requirements and the per-member limit; stock still applies. A role item’s role is given right away.", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "userId", "in": "path", "required": true, "description": "Member’s Discord user ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "integer", "minimum": 1 }, "reason": { "type": [ "string", "null" ], "maxLength": 200, "description": "Shown in the audit log" } }, "required": [ "itemId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "integer" }, "itemId": { "type": [ "integer", "null" ], "description": "null when the item was deleted (the snapshot stays)" }, "storeId": { "type": [ "integer", "null" ] }, "storeName": { "type": [ "string", "null" ] }, "itemName": { "type": "string" }, "itemEmoji": { "type": [ "string", "null" ] }, "itemType": { "type": "string" }, "userId": { "type": "string" }, "price": { "type": "integer", "description": "0 for free grants" }, "status": { "type": "string", "enum": [ "owned", "used", "refunded" ] }, "roleId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "roleRemovedAt": { "type": [ "string", "null" ] }, "fulfillment": { "type": "string", "enum": [ "none", "pending", "done" ] }, "bankTransactionId": { "type": [ "integer", "null" ] }, "refundTransactionId": { "type": [ "integer", "null" ] }, "usedAt": { "type": [ "string", "null" ] }, "refundedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "itemId", "storeId", "storeName", "itemName", "itemEmoji", "itemType", "userId", "price", "status", "roleId", "expiresAt", "roleRemovedAt", "fulfillment", "bankTransactionId", "refundTransactionId", "usedAt", "refundedAt", "createdAt" ] }, "balance": { "type": [ "integer", "null" ], "description": "The member’s balance afterwards (null when unchanged)" } }, "required": [ "purchase", "balance" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`MEMBER_NOT_FOUND` — The user is not a member of the server.\n`SHOP_ITEM_NOT_FOUND` — No Shop item with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "SHOP_ITEM_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "MEMBER_NOT_FOUND": { "value": { "error": "MEMBER_NOT_FOUND", "message": "The user is not a member of the server." } }, "SHOP_ITEM_NOT_FOUND": { "value": { "error": "SHOP_ITEM_NOT_FOUND", "message": "No Shop item with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`SHOP_ITEM_UNAVAILABLE` — The item can’t be bought or granted right now (`reason`: disabled, store_closed, out_of_stock, limit, price_changed, roles, level, already_has_role).\n`ROLE_NOT_GRANTABLE` — The bot can’t give the item’s role (role missing, above the bot, too powerful, or Discord refused). Nothing was charged.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "SHOP_ITEM_UNAVAILABLE", "ROLE_NOT_GRANTABLE" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "SHOP_ITEM_UNAVAILABLE": { "value": { "error": "SHOP_ITEM_UNAVAILABLE", "message": "The item can’t be bought or granted right now." } }, "ROLE_NOT_GRANTABLE": { "value": { "error": "ROLE_NOT_GRANTABLE", "message": "The bot can’t give the item’s role (role missing, above the bot, too powerful, or Discord refused). Nothing was charged." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.\n`BOT_ACCOUNT` — Bots can’t hold a balance.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } }, "BOT_ACCOUNT": { "value": { "error": "BOT_ACCOUNT", "message": "Bots can’t hold a balance." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.grant", "x-botgg-scope": "shop:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "shop", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "SHOP_ITEM_NOT_FOUND", "FEATURE_DISABLED", "SHOP_ITEM_UNAVAILABLE", "ROLE_NOT_GRANTABLE", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/shop/purchases/{purchaseId}/refund": { "post": { "operationId": "shopRefund", "summary": "Refund a purchase", "description": "Like Refund in the console: the price goes back to the member’s balance (one transaction), the purchase becomes `refunded`, optionally restocked; a granted role is removed by the bot within ~30 s.", "tags": [ "shop" ], "security": [ { "apiKey": [ "shop:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "restock": { "type": "boolean", "description": "Put the unit back in stock (default: the Shop’s “restock on refund” setting)" }, "force": { "type": "boolean", "description": "Also refund an item that was already used" }, "reason": { "type": [ "string", "null" ], "maxLength": 200, "description": "Shown in the audit log" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "integer" }, "itemId": { "type": [ "integer", "null" ], "description": "null when the item was deleted (the snapshot stays)" }, "storeId": { "type": [ "integer", "null" ] }, "storeName": { "type": [ "string", "null" ] }, "itemName": { "type": "string" }, "itemEmoji": { "type": [ "string", "null" ] }, "itemType": { "type": "string" }, "userId": { "type": "string" }, "price": { "type": "integer", "description": "0 for free grants" }, "status": { "type": "string", "enum": [ "owned", "used", "refunded" ] }, "roleId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "roleRemovedAt": { "type": [ "string", "null" ] }, "fulfillment": { "type": "string", "enum": [ "none", "pending", "done" ] }, "bankTransactionId": { "type": [ "integer", "null" ] }, "refundTransactionId": { "type": [ "integer", "null" ] }, "usedAt": { "type": [ "string", "null" ] }, "refundedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "itemId", "storeId", "storeName", "itemName", "itemEmoji", "itemType", "userId", "price", "status", "roleId", "expiresAt", "roleRemovedAt", "fulfillment", "bankTransactionId", "refundTransactionId", "usedAt", "refundedAt", "createdAt" ] }, "balance": { "type": [ "integer", "null" ], "description": "The member’s balance afterwards (null when unchanged)" } }, "required": [ "purchase", "balance" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`SHOP_PURCHASE_NOT_FOUND` — No purchase with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "SHOP_PURCHASE_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "SHOP_PURCHASE_NOT_FOUND": { "value": { "error": "SHOP_PURCHASE_NOT_FOUND", "message": "No purchase with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`SHOP_ALREADY_REFUNDED` — The purchase was already refunded.\n`SHOP_ITEM_USED` — The item was already used; refund it with `force: true`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "SHOP_ALREADY_REFUNDED", "SHOP_ITEM_USED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "SHOP_ALREADY_REFUNDED": { "value": { "error": "SHOP_ALREADY_REFUNDED", "message": "The purchase was already refunded." } }, "SHOP_ITEM_USED": { "value": { "error": "SHOP_ITEM_USED", "message": "The item was already used; refund it with force: true." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.\n`BALANCE_LIMIT` — The balance would exceed the maximum.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED", "BALANCE_LIMIT" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } }, "BALANCE_LIMIT": { "value": { "error": "BALANCE_LIMIT", "message": "The balance would exceed the maximum." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "shop.refund", "x-botgg-scope": "shop:write", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "shop", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "SHOP_PURCHASE_NOT_FOUND", "FEATURE_DISABLED", "SHOP_ALREADY_REFUNDED", "SHOP_ITEM_USED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "BALANCE_LIMIT", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/giveaways": { "get": { "operationId": "giveawaysList", "summary": "List giveaways", "description": "`status`: active, scheduled, ended, cancelled or open (= scheduled + active). Running ones by end time, others newest first.", "tags": [ "giveaways" ], "security": [ { "apiKey": [ "giveaways:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "active", "ended", "cancelled", "open" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "scheduled", "active", "ended", "cancelled" ] }, "prize": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "channelId": { "type": "string" }, "messageUrl": { "type": [ "string", "null" ], "description": "null until the bot posted it" }, "winnersCount": { "type": "integer" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string" }, "endedAt": { "type": [ "string", "null" ] }, "entrants": { "type": "integer" }, "entries": { "type": "integer", "description": "Tickets incl. bonus entries" }, "winnerIds": { "type": "array", "items": { "type": "string" } }, "hostId": { "type": "string" }, "requirements": { "type": "object", "additionalProperties": {} }, "pingRoleId": { "type": [ "string", "null" ] }, "dmWinners": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "status", "prize", "description", "channelId", "messageUrl", "winnersCount", "startsAt", "endsAt", "endedAt", "entrants", "entries", "winnerIds", "hostId", "requirements", "pingRoleId", "dmWinners", "createdAt" ] } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "nextPage": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "page", "nextPage" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "giveaways.list", "x-botgg-scope": "giveaways:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "giveaways", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] }, "post": { "operationId": "giveawaysCreate", "summary": "Start a giveaway", "description": "Saved as `scheduled`; the bot posts it in the channel within ~10 s (or at `startsAt`). Same rules as the console editor. Look and DM setting default to the server’s Giveaways settings.", "tags": [ "giveaways" ], "security": [ { "apiKey": [ "giveaways:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channelId": { "type": "string", "pattern": "^\\d{17,20}$" }, "prize": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "winners": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Default 1" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601; omitted / null = start now" }, "endsAt": { "type": "string", "format": "date-time", "description": "ISO 8601; or send durationSeconds" }, "durationSeconds": { "type": "integer", "minimum": 60, "maximum": 5184000, "description": "From the start; or send endsAt" }, "requirements": { "type": "object", "properties": { "roleIds": { "type": "array", "items": { "type": "string", "pattern": "^\\d{17,20}$" }, "maxItems": 20, "default": [] }, "roleMode": { "type": "string", "enum": [ "any", "all" ], "default": "any" }, "blockedRoleIds": { "type": "array", "items": { "type": "string", "pattern": "^\\d{17,20}$" }, "maxItems": 20, "default": [] }, "minAccountAgeDays": { "type": "integer", "minimum": 0, "maximum": 3650, "default": 0 }, "minMemberDays": { "type": "integer", "minimum": 0, "maximum": 3650, "default": 0 }, "minLevel": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 }, "entryCost": { "type": "integer", "minimum": 0, "maximum": 1000000000, "default": 0 }, "bonusRoles": { "type": "array", "items": { "type": "object", "properties": { "roleId": { "type": "string", "pattern": "^\\d{17,20}$" }, "entries": { "type": "integer", "minimum": 2, "maximum": 10 } }, "required": [ "roleId", "entries" ], "additionalProperties": false }, "maxItems": 10, "default": [] } }, "additionalProperties": false, "description": "Required / blocked roles, account and member age, level, entry cost, bonus roles" }, "embed": { "type": "object", "properties": { "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#D94CFF" }, "endedColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#4E5058" }, "emoji": { "type": "string", "minLength": 1, "maxLength": 64, "default": "🎉" }, "imageUrl": { "type": [ "string", "null" ], "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$", "default": null }, "thumbnailUrl": { "type": [ "string", "null" ], "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$", "default": null } }, "additionalProperties": false, "description": "Default: the server’s Giveaways look" }, "pingRoleId": { "type": [ "string", "null" ], "pattern": "^\\d{17,20}$" }, "dmWinners": { "type": "boolean", "description": "Default: the server setting" }, "hostId": { "type": [ "string", "null" ], "pattern": "^\\d{17,20}$", "description": "Shown as the host; default: the API key’s creator" } }, "required": [ "channelId", "prize" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "scheduled", "active", "ended", "cancelled" ] }, "prize": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "channelId": { "type": "string" }, "messageUrl": { "type": [ "string", "null" ], "description": "null until the bot posted it" }, "winnersCount": { "type": "integer" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string" }, "endedAt": { "type": [ "string", "null" ] }, "entrants": { "type": "integer" }, "entries": { "type": "integer", "description": "Tickets incl. bonus entries" }, "winnerIds": { "type": "array", "items": { "type": "string" } }, "hostId": { "type": "string" }, "requirements": { "type": "object", "additionalProperties": {} }, "pingRoleId": { "type": [ "string", "null" ] }, "dmWinners": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "status", "prize", "description", "channelId", "messageUrl", "winnersCount", "startsAt", "endsAt", "endedAt", "entrants", "entries", "winnerIds", "hostId", "requirements", "pingRoleId", "dmWinners", "createdAt" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "402": { "description": "`PLAN_LIMIT` — The server’s plan doesn’t cover this (`limit` reached or `flag` missing).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PLAN_LIMIT" ] } } } ] }, "examples": { "PLAN_LIMIT": { "value": { "error": "PLAN_LIMIT", "message": "The server’s plan doesn’t cover this." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`BANK_DISABLED` — The Bank feature is turned off on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "BANK_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "BANK_DISABLED": { "value": { "error": "BANK_DISABLED", "message": "The Bank feature is turned off on the server." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "giveaways.create", "x-botgg-scope": "giveaways:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "giveaways", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "PLAN_LIMIT", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "BANK_DISABLED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/giveaways/{giveawayId}": { "get": { "operationId": "giveawaysGet", "summary": "Get a giveaway", "description": "With entry counts, winners per draw and the latest queued actions (to follow an end / reroll).", "tags": [ "giveaways" ], "security": [ { "apiKey": [ "giveaways:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "giveawayId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "scheduled", "active", "ended", "cancelled" ] }, "prize": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "channelId": { "type": "string" }, "messageUrl": { "type": [ "string", "null" ], "description": "null until the bot posted it" }, "winnersCount": { "type": "integer" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string" }, "endedAt": { "type": [ "string", "null" ] }, "entrants": { "type": "integer" }, "entries": { "type": "integer", "description": "Tickets incl. bonus entries" }, "winnerIds": { "type": "array", "items": { "type": "string" } }, "hostId": { "type": "string" }, "requirements": { "type": "object", "additionalProperties": {} }, "pingRoleId": { "type": [ "string", "null" ] }, "dmWinners": { "type": "boolean" }, "createdAt": { "type": "string" }, "winners": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "draw": { "type": "integer", "description": "0 = the end draw, 1.. = rerolls" }, "drawnAt": { "type": "string" } }, "required": [ "userId", "draw", "drawnAt" ] } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "done", "failed" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "processedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "action", "status", "error", "createdAt", "processedAt" ] }, "description": "The latest queued actions (end / reroll / …), newest first" } }, "required": [ "id", "status", "prize", "description", "channelId", "messageUrl", "winnersCount", "startsAt", "endsAt", "endedAt", "entrants", "entries", "winnerIds", "hostId", "requirements", "pingRoleId", "dmWinners", "createdAt", "winners", "actions" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`GIVEAWAY_NOT_FOUND` — No giveaway with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "GIVEAWAY_NOT_FOUND": { "value": { "error": "GIVEAWAY_NOT_FOUND", "message": "No giveaway with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "giveaways.get", "x-botgg-scope": "giveaways:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "giveaways", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/giveaways/{giveawayId}/entries": { "get": { "operationId": "giveawaysListEntries", "summary": "List a giveaway’s entrants", "description": "Ordered by user id. Pass `after=` for the next page. `weight` = tickets (bonus roles), `paid` = entry cost paid.", "tags": [ "giveaways" ], "security": [ { "apiKey": [ "giveaways:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "giveawayId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "weight": { "type": "integer" }, "paid": { "type": "integer" }, "enteredAt": { "type": "string" } }, "required": [ "userId", "weight", "paid", "enteredAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`GIVEAWAY_NOT_FOUND` — No giveaway with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "GIVEAWAY_NOT_FOUND": { "value": { "error": "GIVEAWAY_NOT_FOUND", "message": "No giveaway with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "giveaways.listEntries", "x-botgg-scope": "giveaways:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "giveaways", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/giveaways/{giveawayId}/end": { "post": { "operationId": "giveawaysEnd", "summary": "End a giveaway now", "description": "Queued for the bot, which draws the winners and announces them within ~5 s (202). Follow it with GET …/giveaways/{giveawayId}.", "tags": [ "giveaways" ], "security": [ { "apiKey": [ "giveaways:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "giveawayId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "giveawayId": { "type": "integer" }, "action": { "type": "object", "properties": { "id": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "done", "failed" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "processedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "action", "status", "error", "createdAt", "processedAt" ] } }, "required": [ "giveawayId", "action" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`GIVEAWAY_NOT_FOUND` — No giveaway with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "GIVEAWAY_NOT_FOUND": { "value": { "error": "GIVEAWAY_NOT_FOUND", "message": "No giveaway with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`GIVEAWAY_BAD_STATE` — The giveaway’s status doesn’t allow this (`status`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "GIVEAWAY_BAD_STATE" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "GIVEAWAY_BAD_STATE": { "value": { "error": "GIVEAWAY_BAD_STATE", "message": "The giveaway’s status doesn’t allow this." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "giveaways.end", "x-botgg-scope": "giveaways:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "giveaways", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND", "FEATURE_DISABLED", "GIVEAWAY_BAD_STATE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/giveaways/{giveawayId}/reroll": { "post": { "operationId": "giveawaysReroll", "summary": "Reroll winners", "description": "For an ended giveaway: the bot draws `count` new winners (never someone who already won) within ~5 s (202).", "tags": [ "giveaways" ], "security": [ { "apiKey": [ "giveaways:write" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "giveawayId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Default 1" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "giveawayId": { "type": "integer" }, "action": { "type": "object", "properties": { "id": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "done", "failed" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "processedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "action", "status", "error", "createdAt", "processedAt" ] } }, "required": [ "giveawayId", "action" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`GIVEAWAY_NOT_FOUND` — No giveaway with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "GIVEAWAY_NOT_FOUND": { "value": { "error": "GIVEAWAY_NOT_FOUND", "message": "No giveaway with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`GIVEAWAY_BAD_STATE` — The giveaway’s status doesn’t allow this (`status`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "GIVEAWAY_BAD_STATE" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "GIVEAWAY_BAD_STATE": { "value": { "error": "GIVEAWAY_BAD_STATE", "message": "The giveaway’s status doesn’t allow this." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "giveaways.reroll", "x-botgg-scope": "giveaways:write", "x-botgg-sensitive": false, "x-botgg-access": "write", "x-botgg-feature": "giveaways", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "GIVEAWAY_NOT_FOUND", "FEATURE_DISABLED", "GIVEAWAY_BAD_STATE", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/flows": { "get": { "operationId": "flowsList", "summary": "List flows", "tags": [ "flows" ], "security": [ { "apiKey": [ "flows:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "triggerType": { "type": [ "string", "null" ], "description": "e.g. trigger.manual, trigger.webhook, trigger.discord.messageCreated" }, "runnable": { "type": "boolean", "description": "Can be run with POST …/runs (enabled + Manual or Webhook trigger)" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "enabled", "triggerType", "runnable", "updatedAt" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "flows.list", "x-botgg-scope": "flows:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "automations", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/flows/runs/{executionId}": { "get": { "operationId": "flowsGetRun", "summary": "Get a flow run", "description": "Status of a run (any run of this server’s flows); `output` is the last node’s output once it finished.", "tags": [ "flows" ], "security": [ { "apiKey": [ "flows:read" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,15}$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionId": { "type": "integer" }, "workflowId": { "type": "integer" }, "status": { "type": "string", "description": "running | success | error | stopped | cancelled" }, "output": { "anyOf": [ {}, { "type": "null" } ], "description": "The last node’s output (finished runs only)" }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ] } }, "required": [ "executionId", "workflowId", "status", "output", "error", "startedAt", "finishedAt", "durationMs" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`FLOW_EXECUTION_NOT_FOUND` — No flow run with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "FLOW_EXECUTION_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "FLOW_EXECUTION_NOT_FOUND": { "value": { "error": "FLOW_EXECUTION_NOT_FOUND", "message": "No flow run with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "flows.getRun", "x-botgg-scope": "flows:read", "x-botgg-sensitive": false, "x-botgg-access": "read", "x-botgg-feature": "automations", "x-botgg-idempotent": false, "x-botgg-errors": [ "INVALID_REQUEST", "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FLOW_EXECUTION_NOT_FOUND", "FEATURE_DISABLED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } }, "/guilds/{guildId}/flows/{workflowId}/runs": { "post": { "operationId": "flowsRun", "summary": "Run a flow", "description": "Only enabled flows with a Manual or Webhook trigger. A Webhook flow runs as if its webhook URL was called with `input` as the JSON body. Counts toward the plan’s daily runs. 202 `{ executionId, status: \"running\" }`, or with `wait: true` 200 with the final status and output (202 when it is still running after the timeout — poll GET …/flows/runs/{executionId}).", "tags": [ "flows" ], "security": [ { "apiKey": [ "flows:run" ] } ], "parameters": [ { "name": "guildId", "in": "path", "required": true, "description": "Server (guild) ID", "schema": { "type": "string", "pattern": "^\\d{17,20}$" } }, { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,15}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Trigger data (any JSON): `$trigger` for Manual flows, `$trigger.body` for Webhook flows" }, "wait": { "type": "boolean", "description": "Wait for the run to finish (default false → 202 right after it started)" }, "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 120, "description": "Longest wait; default = the flow timeout + 5 s" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionId": { "type": "integer" }, "workflowId": { "type": "integer" }, "status": { "type": "string", "description": "running | success | error | stopped | cancelled" }, "output": { "anyOf": [ {}, { "type": "null" } ], "description": "The last node’s output (finished runs only)" }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ] } }, "required": [ "executionId", "workflowId", "status", "output", "error", "startedAt", "finishedAt", "durationMs" ] } } } }, "400": { "description": "`INVALID_REQUEST` — Invalid path id, query parameter, header or body (see `issues`).\n`INVALID_JSON` — The body is not valid JSON.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INVALID_REQUEST", "INVALID_JSON" ] } } } ] }, "examples": { "INVALID_REQUEST": { "value": { "error": "INVALID_REQUEST", "message": "Invalid path id, query parameter, header or body." } }, "INVALID_JSON": { "value": { "error": "INVALID_JSON", "message": "The body is not valid JSON." } } } } } }, "401": { "description": "`UNAUTHORIZED` — Missing or malformed `Authorization: Bearer` header.\n`INVALID_API_KEY` — Unknown API key.\n`API_KEY_REVOKED` — The API key was revoked.\n`API_KEY_EXPIRED` — The API key has expired.", "headers": { "WWW-Authenticate": { "description": "`Bearer realm=\"BotGG API\"`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNAUTHORIZED", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED" ] } } } ] }, "examples": { "UNAUTHORIZED": { "value": { "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization: Bearer header." } }, "INVALID_API_KEY": { "value": { "error": "INVALID_API_KEY", "message": "Unknown API key." } }, "API_KEY_REVOKED": { "value": { "error": "API_KEY_REVOKED", "message": "The API key was revoked." } }, "API_KEY_EXPIRED": { "value": { "error": "API_KEY_EXPIRED", "message": "The API key has expired." } } } } } }, "402": { "description": "`PLAN_LIMIT` — The server’s plan doesn’t cover this (`limit` reached or `flag` missing).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PLAN_LIMIT" ] } } } ] }, "examples": { "PLAN_LIMIT": { "value": { "error": "PLAN_LIMIT", "message": "The server’s plan doesn’t cover this." } } } } } }, "403": { "description": "`BROWSER_REQUESTS_NOT_ALLOWED` — Request sent with an Origin header (from a browser). The API is server-to-server only.\n`GUILD_MISMATCH` — The API key belongs to another server.\n`INSUFFICIENT_SCOPE` — The API key lacks the scope this endpoint needs (`required`).\n`GUILD_BLOCKED` — The server is blocked from BotGG.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED" ] } } } ] }, "examples": { "BROWSER_REQUESTS_NOT_ALLOWED": { "value": { "error": "BROWSER_REQUESTS_NOT_ALLOWED", "message": "Request sent with an Origin header (from a browser). The API is server-to-server only." } }, "GUILD_MISMATCH": { "value": { "error": "GUILD_MISMATCH", "message": "The API key belongs to another server." } }, "INSUFFICIENT_SCOPE": { "value": { "error": "INSUFFICIENT_SCOPE", "message": "The API key lacks the scope this endpoint needs." } }, "GUILD_BLOCKED": { "value": { "error": "GUILD_BLOCKED", "message": "The server is blocked from BotGG." } } } } } }, "404": { "description": "`BOT_NOT_IN_GUILD` — The bot is not in this server.\n`FLOW_NOT_FOUND` — No flow with this id on the server.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "BOT_NOT_IN_GUILD", "FLOW_NOT_FOUND" ] } } } ] }, "examples": { "BOT_NOT_IN_GUILD": { "value": { "error": "BOT_NOT_IN_GUILD", "message": "The bot is not in this server." } }, "FLOW_NOT_FOUND": { "value": { "error": "FLOW_NOT_FOUND", "message": "No flow with this id on the server." } } } } } }, "409": { "description": "`FEATURE_DISABLED` — The feature this endpoint uses is turned off on the server (`feature`).\n`FLOW_NOT_RUNNABLE` — Only flows that start with a Manual or Webhook trigger can be run (`triggerType`).\n`FLOW_DISABLED` — The flow is turned off.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "FEATURE_DISABLED", "FLOW_NOT_RUNNABLE", "FLOW_DISABLED" ] } } } ] }, "examples": { "FEATURE_DISABLED": { "value": { "error": "FEATURE_DISABLED", "message": "The feature this endpoint uses is turned off on the server." } }, "FLOW_NOT_RUNNABLE": { "value": { "error": "FLOW_NOT_RUNNABLE", "message": "Only flows that start with a Manual or Webhook trigger can be run." } }, "FLOW_DISABLED": { "value": { "error": "FLOW_DISABLED", "message": "The flow is turned off." } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — The body is larger than allowed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "PAYLOAD_TOO_LARGE" ] } } } ] }, "examples": { "PAYLOAD_TOO_LARGE": { "value": { "error": "PAYLOAD_TOO_LARGE", "message": "The body is larger than allowed." } } } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — The body must be `application/json`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] } } } ] }, "examples": { "UNSUPPORTED_MEDIA_TYPE": { "value": { "error": "UNSUPPORTED_MEDIA_TYPE", "message": "The body must be application/json." } } } } } }, "422": { "description": "`IDEMPOTENCY_KEY_REUSED` — The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "IDEMPOTENCY_KEY_REUSED" ] } } } ] }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "value": { "error": "IDEMPOTENCY_KEY_REUSED", "message": "The Idempotency-Key was already used with a different request." } } } } } }, "429": { "description": "`RATE_LIMITED` — Too many requests (see `Retry-After`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "RATE_LIMITED" ] } } } ] }, "examples": { "RATE_LIMITED": { "value": { "error": "RATE_LIMITED", "message": "Too many requests." } } } } } }, "500": { "description": "`INTERNAL` — Unexpected server error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "INTERNAL" ] } } } ] }, "examples": { "INTERNAL": { "value": { "error": "INTERNAL", "message": "Unexpected server error." } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "enum": [ "SERVICE_UNAVAILABLE" ] } } } ] }, "examples": { "SERVICE_UNAVAILABLE": { "value": { "error": "SERVICE_UNAVAILABLE", "message": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } } } } } } }, "x-botgg-id": "flows.run", "x-botgg-scope": "flows:run", "x-botgg-sensitive": true, "x-botgg-access": "write", "x-botgg-feature": "automations", "x-botgg-idempotent": true, "x-botgg-errors": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "PLAN_LIMIT", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "BOT_NOT_IN_GUILD", "FLOW_NOT_FOUND", "FEATURE_DISABLED", "FLOW_NOT_RUNNABLE", "FLOW_DISABLED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ] } } }, "webhooks": { "bank.transaction": { "post": { "operationId": "webhookBankTransaction", "summary": "Bank transaction", "description": "Any balance change: daily rewards, transfers, shop charges, staff and API changes.", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "bank.transaction", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "transactionId": { "type": "integer", "minimum": 0 }, "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "type": { "type": "string", "description": "Ledger type: daily, transfer_in, transfer_out, fee, admin_add, admin_remove, admin_set, flow, api, …" }, "amount": { "type": "integer", "description": "Signed change (negative = debit)" }, "balanceAfter": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "counterpartyId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "actorId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "transactionId", "userId", "type", "amount", "balanceAfter", "reason", "counterpartyId", "actorId", "createdAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "bank", "x-botgg-label": { "en": "Bank transaction", "ru": "Операция Банка", "he": "תנועה בבנק" }, "x-botgg-description": { "en": "Any balance change: daily rewards, transfers, shop charges, staff and API changes.", "ru": "Любое изменение баланса: ежедневные награды, переводы, покупки, изменения персонала и через API.", "he": "כל שינוי ביתרה: פרסים יומיים, העברות, חיובי חנות, שינויים של הצוות ודרך ה-API." } } }, "levels.levelUp": { "post": { "operationId": "webhookLevelsLevelUp", "summary": "Level up", "description": "A member reached a higher level (activity or a staff change).", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "levels.levelUp", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "level": { "type": "integer", "minimum": 0 }, "previousLevel": { "type": "integer", "minimum": 0 }, "source": { "type": "string", "enum": [ "activity", "admin" ] } }, "required": [ "userId", "level", "previousLevel", "source" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "levels", "x-botgg-label": { "en": "Level up", "ru": "Новый уровень", "he": "עלייה ברמה" }, "x-botgg-description": { "en": "A member reached a higher level (activity or a staff change).", "ru": "Участник достиг более высокого уровня (за активность или по решению персонала).", "he": "חבר הגיע לרמה גבוהה יותר (פעילות או שינוי של הצוות)." } } }, "shop.purchase": { "post": { "operationId": "webhookShopPurchase", "summary": "Purchase", "description": "A member bought a Shop item.", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "shop.purchase", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "purchaseId": { "type": "integer", "minimum": 0 }, "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "item": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "description": "null when the item was deleted since" }, "name": { "type": "string" }, "emoji": { "type": [ "string", "null" ] }, "type": { "type": "string", "description": "role | color | item | …" } }, "required": [ "id", "name", "emoji", "type" ] }, "store": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0 }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "description": "id/name null = the built-in Main store" }, "price": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "description": "owned | used | refunded" }, "roleId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "purchaseId", "userId", "item", "store", "price", "status", "roleId", "expiresAt", "createdAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "shop", "x-botgg-label": { "en": "Purchase", "ru": "Покупка", "he": "רכישה" }, "x-botgg-description": { "en": "A member bought a Shop item.", "ru": "Участник купил товар в Магазине.", "he": "חבר קנה פריט בחנות." } } }, "shop.refund": { "post": { "operationId": "webhookShopRefund", "summary": "Refund", "description": "A Shop purchase was refunded.", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "shop.refund", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "purchaseId": { "type": "integer", "minimum": 0 }, "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "item": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "description": "null when the item was deleted since" }, "name": { "type": "string" }, "emoji": { "type": [ "string", "null" ] }, "type": { "type": "string", "description": "role | color | item | …" } }, "required": [ "id", "name", "emoji", "type" ] }, "price": { "type": "integer", "minimum": 0 }, "refundedBy": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "refundedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "purchaseId", "userId", "item", "price", "refundedBy", "refundedAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "shop", "x-botgg-label": { "en": "Refund", "ru": "Возврат", "he": "החזר" }, "x-botgg-description": { "en": "A Shop purchase was refunded.", "ru": "Покупка в Магазине возвращена.", "he": "רכישה בחנות הוחזרה." } } }, "tickets.opened": { "post": { "operationId": "webhookTicketsOpened", "summary": "Ticket opened", "description": "A ticket channel or thread was created.", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "tickets.opened", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "ticketId": { "type": "integer", "minimum": 0 }, "number": { "type": "integer", "exclusiveMinimum": 0 }, "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "panelId": { "type": [ "integer", "null" ], "minimum": 0 }, "channelId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "subject": { "type": [ "string", "null" ] }, "openedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "ticketId", "number", "userId", "panelId", "channelId", "subject", "openedAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "tickets", "x-botgg-label": { "en": "Ticket opened", "ru": "Тикет открыт", "he": "כרטיס נפתח" }, "x-botgg-description": { "en": "A ticket channel or thread was created.", "ru": "Создан канал или ветка тикета.", "he": "נוצר ערוץ או שרשור של כרטיס." } } }, "tickets.closed": { "post": { "operationId": "webhookTicketsClosed", "summary": "Ticket closed", "description": "A ticket was closed (manually, automatically or because the opener left).", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "tickets.closed", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "ticketId": { "type": "integer", "minimum": 0 }, "number": { "type": "integer", "exclusiveMinimum": 0 }, "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "panelId": { "type": [ "integer", "null" ], "minimum": 0 }, "channelId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "closedBy": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "closeReason": { "type": [ "string", "null" ] }, "closeType": { "type": [ "string", "null" ], "description": "manual | auto | leave | …" }, "openedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "closedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "ticketId", "number", "userId", "panelId", "channelId", "closedBy", "closeReason", "closeType", "openedAt", "closedAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "tickets", "x-botgg-label": { "en": "Ticket closed", "ru": "Тикет закрыт", "he": "כרטיס נסגר" }, "x-botgg-description": { "en": "A ticket was closed (manually, automatically or because the opener left).", "ru": "Тикет закрыт (вручную, автоматически или после ухода автора).", "he": "כרטיס נסגר (ידנית, אוטומטית או כי הפותח עזב)." } } }, "members.joined": { "post": { "operationId": "webhookMembersJoined", "summary": "Member joined", "description": "Someone joined the server.", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "members.joined", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "bot": { "type": "boolean" }, "joinedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "accountCreatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "userId", "bot", "joinedAt", "accountCreatedAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "members", "x-botgg-label": { "en": "Member joined", "ru": "Участник пришёл", "he": "חבר הצטרף" }, "x-botgg-description": { "en": "Someone joined the server.", "ru": "Кто-то присоединился к серверу.", "he": "מישהו הצטרף לשרת." } } }, "members.left": { "post": { "operationId": "webhookMembersLeft", "summary": "Member left", "description": "Someone left the server (or was kicked / banned).", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "members.left", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "bot": { "type": "boolean" }, "leftAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "userId", "bot", "leftAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "members", "x-botgg-label": { "en": "Member left", "ru": "Участник ушёл", "he": "חבר עזב" }, "x-botgg-description": { "en": "Someone left the server (or was kicked / banned).", "ru": "Кто-то покинул сервер (или был исключён / забанен).", "he": "מישהו עזב את השרת (או הורחק / נחסם)." } } }, "giveaways.ended": { "post": { "operationId": "webhookGiveawaysEnded", "summary": "Giveaway ended", "description": "A giveaway ended and its winners were drawn.", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "giveaways.ended", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "giveawayId": { "type": "integer", "minimum": 0 }, "prize": { "type": "string" }, "channelId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "messageId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "hostId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "winnerIds": { "type": "array", "items": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" } }, "entrants": { "type": "integer", "minimum": 0 }, "endedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "giveawayId", "prize", "channelId", "messageId", "hostId", "winnerIds", "entrants", "endedAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "giveaways", "x-botgg-label": { "en": "Giveaway ended", "ru": "Розыгрыш завершён", "he": "הגרלה הסתיימה" }, "x-botgg-description": { "en": "A giveaway ended and its winners were drawn.", "ru": "Розыгрыш завершён, победители выбраны.", "he": "הגרלה הסתיימה והזוכים נבחרו." } } }, "moderation.caseCreated": { "post": { "operationId": "webhookModerationCaseCreated", "summary": "Moderation case", "description": "A new moderation case (warn, timeout, kick, ban, …) was recorded.", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "moderation.caseCreated", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "caseId": { "type": "integer", "minimum": 0 }, "number": { "type": "integer", "exclusiveMinimum": 0 }, "action": { "type": "string", "description": "warn | timeout | kick | ban | tempban | unban | …" }, "targetId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "moderatorId": { "type": [ "string", "null" ], "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "reason": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 0 }, "source": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "caseId", "number", "action", "targetId", "moderatorId", "reason", "durationSeconds", "source", "expiresAt", "createdAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "moderation", "x-botgg-label": { "en": "Moderation case", "ru": "Случай модерации", "he": "תיק ניהול" }, "x-botgg-description": { "en": "A new moderation case (warn, timeout, kick, ban, …) was recorded.", "ru": "Записан новый случай модерации (предупреждение, тайм-аут, кик, бан, …).", "he": "נרשם תיק ניהול חדש (אזהרה, השתקה, הרחקה, חסימה, …)." } } }, "applications.submitted": { "post": { "operationId": "webhookApplicationsSubmitted", "summary": "Application submitted", "description": "A member submitted an application form (answers included).", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "applications.submitted", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "submissionId": { "type": "integer", "minimum": 0 }, "number": { "type": "integer", "exclusiveMinimum": 0 }, "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "formId": { "type": [ "integer", "null" ], "minimum": 0 }, "formTitle": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "description": "Question type, e.g. short, paragraph, select, number, yesno" }, "value": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "text": { "type": [ "string", "null" ], "description": "Human-readable answer (as shown in Discord), or null" } }, "required": [ "questionId", "label", "type", "value", "text" ] } }, "submittedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "submissionId", "number", "userId", "formId", "formTitle", "status", "answers", "submittedAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "applications", "x-botgg-label": { "en": "Application submitted", "ru": "Заявка отправлена", "he": "מועמדות נשלחה" }, "x-botgg-description": { "en": "A member submitted an application form (answers included).", "ru": "Участник отправил форму заявки (с ответами).", "he": "חבר שלח טופס מועמדות (כולל התשובות)." } } }, "appeals.submitted": { "post": { "operationId": "webhookAppealsSubmitted", "summary": "Ban appeal submitted", "description": "A banned user filed a ban appeal (answers included).", "tags": [ "webhooks" ], "parameters": [ { "name": "BotGG-Webhook-Id", "in": "header", "required": true, "description": "Event id (`evt_…`), the same on every retry — use it to deduplicate.", "schema": { "type": "string" } }, { "name": "BotGG-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix time (seconds) when this attempt was signed.", "schema": { "type": "string" } }, { "name": "BotGG-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the request (see /developers/webhooks/).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,32}$", "description": "Event id, also sent as BotGG-Webhook-Id; the same on every retry" }, "type": { "const": "appeals.submitted", "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" }, "guildId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "data": { "type": "object", "properties": { "appealId": { "type": "integer", "minimum": 0 }, "number": { "type": "integer", "exclusiveMinimum": 0 }, "userId": { "type": "string", "pattern": "^\\d{15,22}$", "description": "Discord snowflake id" }, "banCaseNumber": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "banReason": { "type": [ "string", "null" ] }, "answers": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "description": "Question type, e.g. short, paragraph, select, number, yesno" }, "value": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "text": { "type": [ "string", "null" ], "description": "Human-readable answer (as shown in Discord), or null" } }, "required": [ "questionId", "label", "type", "value", "text" ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (UTC)" } }, "required": [ "appealId", "number", "userId", "banCaseNumber", "banReason", "answers", "createdAt" ] } }, "required": [ "id", "type", "createdAt", "guildId", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery; anything else (or a timeout) is retried with backoff." } }, "x-botgg-group": "appeals", "x-botgg-label": { "en": "Ban appeal submitted", "ru": "Апелляция отправлена", "he": "ערעור נשלח" }, "x-botgg-description": { "en": "A banned user filed a ban appeal (answers included).", "ru": "Забаненный пользователь подал апелляцию (с ответами).", "he": "משתמש חסום הגיש ערעור (כולל התשובות)." } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "botgg_<43 base64url chars>", "description": "Per-server API key from the console. The scopes listed on each operation are required (scopes are independent: write does not imply read)." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a retried write safe: the first successful response is stored for 24 h per API key and replayed (with `Idempotent-Replayed: true`) for the same key + request; the same key with a different request → 422 `IDEMPOTENCY_KEY_REUSED`. Failures are not stored.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7E]{1,100}$", "minLength": 1, "maxLength": 100 }, "example": "5f0c6a2e-8d4b-4c1e-9a7f-2b3c4d5e6f70" } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this API key (plan limit).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current one-minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` when this is a stored response replayed for a repeated Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST", "INVALID_JSON", "UNAUTHORIZED", "PLAN_LIMIT", "INVALID_API_KEY", "API_KEY_REVOKED", "API_KEY_EXPIRED", "BROWSER_REQUESTS_NOT_ALLOWED", "GUILD_MISMATCH", "INSUFFICIENT_SCOPE", "GUILD_BLOCKED", "SELF_DECISION", "MODERATOR_NOT_MEMBER", "MODERATOR_MISSING_PERMISSION", "HIERARCHY", "NOT_FOUND", "TICKET_NOT_FOUND", "TRANSCRIPT_NOT_FOUND", "APPLICATION_NOT_FOUND", "APPEAL_NOT_FOUND", "CASE_NOT_FOUND", "MODERATION_ACTION_NOT_FOUND", "BOT_NOT_IN_GUILD", "MEMBER_NOT_FOUND", "XP_CHANGE_NOT_FOUND", "SHOP_STORE_NOT_FOUND", "SHOP_ITEM_NOT_FOUND", "SHOP_PURCHASE_NOT_FOUND", "GIVEAWAY_NOT_FOUND", "FLOW_NOT_FOUND", "FLOW_EXECUTION_NOT_FOUND", "FEATURE_DISABLED", "BANK_DISABLED", "INSUFFICIENT_FUNDS", "SHOP_ITEM_UNAVAILABLE", "SHOP_ALREADY_REFUNDED", "SHOP_ITEM_USED", "ROLE_NOT_GRANTABLE", "GIVEAWAY_BAD_STATE", "FLOW_NOT_RUNNABLE", "FLOW_DISABLED", "TICKET_CLOSED", "ALREADY_DECIDED", "NOT_BANNED", "BOT_MISSING_PERMISSIONS", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_REUSED", "BOT_ACCOUNT", "BALANCE_LIMIT", "RATE_LIMITED", "INTERNAL", "SERVICE_UNAVAILABLE" ], "description": "Stable machine-readable code — branch on this." }, "message": { "type": "string", "description": "Human-readable explanation (may change)." }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "`INVALID_REQUEST`: what is wrong; paths start with `params.`, `query.`, `body.` or `header.`." }, "required": { "type": "string", "description": "`INSUFFICIENT_SCOPE`: the scope the endpoint needs." }, "retryAfter": { "type": "integer", "description": "Seconds to wait (`RATE_LIMITED`, some `SERVICE_UNAVAILABLE`)." }, "feature": { "type": "string", "description": "`FEATURE_DISABLED`: the feature key." } }, "additionalProperties": true } } }, "x-botgg-errors": { "INVALID_REQUEST": { "status": 400, "description": "Invalid path id, query parameter, header or body (see `issues`)." }, "INVALID_JSON": { "status": 400, "description": "The body is not valid JSON." }, "UNAUTHORIZED": { "status": 401, "description": "Missing or malformed `Authorization: Bearer` header." }, "PLAN_LIMIT": { "status": 402, "description": "The server’s plan doesn’t cover this (`limit` reached or `flag` missing)." }, "INVALID_API_KEY": { "status": 401, "description": "Unknown API key." }, "API_KEY_REVOKED": { "status": 401, "description": "The API key was revoked." }, "API_KEY_EXPIRED": { "status": 401, "description": "The API key has expired." }, "BROWSER_REQUESTS_NOT_ALLOWED": { "status": 403, "description": "Request sent with an Origin header (from a browser). The API is server-to-server only." }, "GUILD_MISMATCH": { "status": 403, "description": "The API key belongs to another server." }, "INSUFFICIENT_SCOPE": { "status": 403, "description": "The API key lacks the scope this endpoint needs (`required`)." }, "GUILD_BLOCKED": { "status": 403, "description": "The server is blocked from BotGG." }, "SELF_DECISION": { "status": 403, "description": "The API key’s creator can’t decide their own application or appeal." }, "MODERATOR_NOT_MEMBER": { "status": 403, "description": "The API key’s creator is no longer a member of the server (moderation acts in their name)." }, "MODERATOR_MISSING_PERMISSION": { "status": 403, "description": "The API key’s creator lacks the Discord permission for this action (`required`)." }, "HIERARCHY": { "status": 403, "description": "The target can’t be moderated (`reason`: self = the key’s creator, bot, owner, higher = not below the creator’s highest role, botHigher = not below the bot’s)." }, "NOT_FOUND": { "status": 404, "description": "No such endpoint." }, "TICKET_NOT_FOUND": { "status": 404, "description": "No ticket with this number on the server." }, "TRANSCRIPT_NOT_FOUND": { "status": 404, "description": "The ticket has no saved transcript (still open, transcripts off, or deleted)." }, "APPLICATION_NOT_FOUND": { "status": 404, "description": "No application (or form) with this number / id on the server." }, "APPEAL_NOT_FOUND": { "status": 404, "description": "No ban appeal with this number on the server." }, "CASE_NOT_FOUND": { "status": 404, "description": "No moderation case with this number on the server." }, "MODERATION_ACTION_NOT_FOUND": { "status": 404, "description": "No moderation action with this id was made with this API key." }, "BOT_NOT_IN_GUILD": { "status": 404, "description": "The bot is not in this server." }, "MEMBER_NOT_FOUND": { "status": 404, "description": "The user is not a member of the server." }, "XP_CHANGE_NOT_FOUND": { "status": 404, "description": "No XP change with this id was made with this API key." }, "SHOP_STORE_NOT_FOUND": { "status": 404, "description": "No store with this id on the server." }, "SHOP_ITEM_NOT_FOUND": { "status": 404, "description": "No Shop item with this id on the server." }, "SHOP_PURCHASE_NOT_FOUND": { "status": 404, "description": "No purchase with this id on the server." }, "GIVEAWAY_NOT_FOUND": { "status": 404, "description": "No giveaway with this id on the server." }, "FLOW_NOT_FOUND": { "status": 404, "description": "No flow with this id on the server." }, "FLOW_EXECUTION_NOT_FOUND": { "status": 404, "description": "No flow run with this id on the server." }, "FEATURE_DISABLED": { "status": 409, "description": "The feature this endpoint uses is turned off on the server (`feature`)." }, "BANK_DISABLED": { "status": 409, "description": "The Bank feature is turned off on the server." }, "INSUFFICIENT_FUNDS": { "status": 409, "description": "A remove would make the balance negative (`balance`)." }, "SHOP_ITEM_UNAVAILABLE": { "status": 409, "description": "The item can’t be bought or granted right now (`reason`: disabled, store_closed, out_of_stock, limit, price_changed, roles, level, already_has_role)." }, "SHOP_ALREADY_REFUNDED": { "status": 409, "description": "The purchase was already refunded." }, "SHOP_ITEM_USED": { "status": 409, "description": "The item was already used; refund it with `force: true`." }, "ROLE_NOT_GRANTABLE": { "status": 409, "description": "The bot can’t give the item’s role (role missing, above the bot, too powerful, or Discord refused). Nothing was charged." }, "GIVEAWAY_BAD_STATE": { "status": 409, "description": "The giveaway’s status doesn’t allow this (`status`)." }, "FLOW_NOT_RUNNABLE": { "status": 409, "description": "Only flows that start with a Manual or Webhook trigger can be run (`triggerType`)." }, "FLOW_DISABLED": { "status": 409, "description": "The flow is turned off." }, "TICKET_CLOSED": { "status": 409, "description": "The ticket is already closed." }, "ALREADY_DECIDED": { "status": 409, "description": "The application or appeal was already decided (`status`)." }, "NOT_BANNED": { "status": 409, "description": "The user is not banned from the server." }, "BOT_MISSING_PERMISSIONS": { "status": 409, "description": "The bot lacks the Discord permission for this action (`missing`)." }, "PAYLOAD_TOO_LARGE": { "status": 413, "description": "The body is larger than allowed." }, "UNSUPPORTED_MEDIA_TYPE": { "status": 415, "description": "The body must be `application/json`." }, "IDEMPOTENCY_KEY_REUSED": { "status": 422, "description": "The Idempotency-Key was already used with a different request." }, "BOT_ACCOUNT": { "status": 422, "description": "Bots can’t hold a balance." }, "BALANCE_LIMIT": { "status": 422, "description": "The balance would exceed the maximum." }, "RATE_LIMITED": { "status": 429, "description": "Too many requests (see `Retry-After`)." }, "INTERNAL": { "status": 500, "description": "Unexpected server error." }, "SERVICE_UNAVAILABLE": { "status": 503, "description": "A dependency (Discord) is unreachable or the feature is paused by BotGG. Retry later." } }, "x-botgg-webhook-groups": [ { "key": "bank", "label": { "en": "Bank", "ru": "Банк", "he": "בנק" } }, { "key": "levels", "label": { "en": "Levels", "ru": "Уровни", "he": "רמות" } }, { "key": "shop", "label": { "en": "Shop", "ru": "Магазин", "he": "חנות" } }, { "key": "tickets", "label": { "en": "Tickets", "ru": "Тикеты", "he": "כרטיסים" } }, { "key": "members", "label": { "en": "Members", "ru": "Участники", "he": "חברים" } }, { "key": "giveaways", "label": { "en": "Giveaways", "ru": "Розыгрыши", "he": "הגרלות" } }, { "key": "moderation", "label": { "en": "Moderation", "ru": "Модерация", "he": "ניהול" } }, { "key": "applications", "label": { "en": "Applications", "ru": "Заявки", "he": "מועמדויות" } }, { "key": "appeals", "label": { "en": "Ban appeals", "ru": "Апелляции", "he": "ערעורים" } } ], "x-botgg-scopes": [ { "key": "guild:read", "group": "guild", "access": "read", "sensitive": false, "label": { "en": "Read server info", "ru": "Чтение данных сервера", "he": "קריאת פרטי השרת" }, "description": { "en": "Server name, icon, member count, language and enabled features; roles, channels and basic member info (roles, nickname, join date).", "ru": "Название, иконка, число участников, язык и включённые функции сервера; роли, каналы и основные данные участника (роли, ник, дата входа).", "he": "שם השרת, סמל, מספר חברים, שפה ותכונות מופעלות; תפקידים, ערוצים ופרטי חבר בסיסיים (תפקידים, כינוי, תאריך הצטרפות)." } }, { "key": "bank:read", "group": "bank", "access": "read", "sensitive": false, "label": { "en": "Read Bank", "ru": "Чтение Банка", "he": "קריאת הבנק" }, "description": { "en": "Balances, a member’s transaction history and the leaderboard.", "ru": "Балансы, история операций участника и таблица лидеров.", "he": "יתרות, היסטוריית התנועות של חבר והטבלה המובילה." } }, { "key": "bank:write", "group": "bank", "access": "write", "sensitive": false, "label": { "en": "Change balances", "ru": "Изменение балансов", "he": "שינוי יתרות" }, "description": { "en": "Add currency to or remove it from members. Every change is written to the Bank ledger.", "ru": "Начислять и списывать валюту участникам. Каждое изменение попадает в журнал Банка.", "he": "הוספה והורדה של מטבע לחברים. כל שינוי נרשם ביומן הבנק." } }, { "key": "levels:read", "group": "levels", "access": "read", "sensitive": false, "label": { "en": "Read Levels", "ru": "Чтение Уровней", "he": "קריאת הרמות" }, "description": { "en": "A member’s level, XP and rank, and the XP leaderboard.", "ru": "Уровень, опыт и место участника, таблица лидеров по опыту.", "he": "הרמה, ה-XP והדירוג של חבר, וטבלת המובילים לפי XP." } }, { "key": "levels:write", "group": "levels", "access": "write", "sensitive": false, "label": { "en": "Change XP", "ru": "Изменение опыта", "he": "שינוי XP" }, "description": { "en": "Add, remove or set members’ XP. Reward roles and level-up announcements work as with /levels commands; every change is in the audit log.", "ru": "Начислять, списывать и задавать опыт участникам. Роли-награды и объявления о новом уровне работают как с командами /levels; каждое изменение попадает в журнал аудита.", "he": "הוספה, הורדה וקביעה של XP לחברים. תפקידי פרס והכרזות עליית רמה פועלים כמו בפקודות /levels; כל שינוי נרשם ביומן הפעולות." } }, { "key": "invites:read", "group": "invites", "access": "read", "sensitive": false, "label": { "en": "Read invites", "ru": "Чтение приглашений", "he": "קריאת הזמנות" }, "description": { "en": "A member’s invite counts and rank, and the invites leaderboard.", "ru": "Счётчики приглашений и место участника, таблица лидеров по приглашениям.", "he": "מוני ההזמנות והדירוג של חבר, וטבלת המובילים בהזמנות." } }, { "key": "invites:write", "group": "invites", "access": "write", "sensitive": false, "label": { "en": "Change bonus invites", "ru": "Изменение бонусных приглашений", "he": "שינוי הזמנות בונוס" }, "description": { "en": "Add or remove bonus invites, like /invites add. Milestone rewards follow; every change is in the audit log.", "ru": "Добавлять и убирать бонусные приглашения, как /invites add. Награды за рубежи выдаются автоматически; каждое изменение попадает в журнал аудита.", "he": "הוספה והורדה של הזמנות בונוס, כמו /invites add. פרסי אבני דרך מוענקים בהתאם; כל שינוי נרשם ביומן הפעולות." } }, { "key": "shop:read", "group": "shop", "access": "read", "sensitive": false, "label": { "en": "Read Shop", "ru": "Чтение Магазина", "he": "קריאת החנות" }, "description": { "en": "Stores, items, members’ inventories and the purchase history.", "ru": "Магазины, товары, инвентарь участников и история покупок.", "he": "חנויות, פריטים, המלאי של חברים והיסטוריית הרכישות." } }, { "key": "shop:write", "group": "shop", "access": "write", "sensitive": true, "label": { "en": "Manage Shop", "ru": "Управление Магазином", "he": "ניהול החנות" }, "description": { "en": "Buy items for members (charged from their Bank balance, roles are given), grant items for free, refund purchases, restock and turn items on or off.", "ru": "Покупать товары за участников (списывается с их баланса в Банке, роли выдаются), выдавать товары бесплатно, возвращать покупки, пополнять запас и включать или выключать товары.", "he": "קנייה של פריטים עבור חברים (מחויב מיתרת הבנק שלהם, תפקידים מוענקים), הענקת פריטים בחינם, החזר רכישות, חידוש מלאי והפעלה או כיבוי של פריטים." } }, { "key": "giveaways:read", "group": "giveaways", "access": "read", "sensitive": false, "label": { "en": "Read giveaways", "ru": "Чтение розыгрышей", "he": "קריאת הגרלות" }, "description": { "en": "Running and ended giveaways with entry counts, winners and the list of entrants.", "ru": "Идущие и завершённые розыгрыши: число участников, победители и список участников.", "he": "הגרלות פעילות ושהסתיימו, עם מספר המשתתפים, הזוכים ורשימת המשתתפים." } }, { "key": "giveaways:write", "group": "giveaways", "access": "write", "sensitive": false, "label": { "en": "Manage giveaways", "ru": "Управление розыгрышами", "he": "ניהול הגרלות" }, "description": { "en": "Start giveaways, end them early and reroll winners. The bot posts and updates them in Discord.", "ru": "Запускать розыгрыши, завершать их досрочно и перевыбирать победителей. Бот публикует и обновляет их в Discord.", "he": "פתיחת הגרלות, סיום מוקדם שלהן והגרלת זוכים מחדש. הבוט מפרסם ומעדכן אותן ב-Discord." } }, { "key": "flows:read", "group": "flows", "access": "read", "sensitive": false, "label": { "en": "Read Flows", "ru": "Чтение сценариев", "he": "קריאת תהליכים" }, "description": { "en": "The list of flows (name, on/off, trigger) and the status and result of runs.", "ru": "Список сценариев (название, вкл./выкл., триггер), статус и результат запусков.", "he": "רשימת התהליכים (שם, פעיל/כבוי, טריגר) והסטטוס והתוצאה של הרצות." } }, { "key": "flows:run", "group": "flows", "access": "write", "sensitive": true, "label": { "en": "Run Flows", "ru": "Запуск сценариев", "he": "הרצת תהליכים" }, "description": { "en": "Run enabled flows that start with a Manual or Webhook trigger, with your own input. The flow does whatever its steps do; runs count toward the plan’s daily limit.", "ru": "Запускать включённые сценарии с триггером «Вручную» или «Вебхук» со своими входными данными. Сценарий выполняет все свои шаги; запуски учитываются в дневном лимите тарифа.", "he": "הרצת תהליכים פעילים שמתחילים בטריגר ידני או Webhook, עם קלט משלך. התהליך מבצע את כל השלבים שלו; ההרצות נספרות במגבלה היומית של התוכנית." } }, { "key": "tickets:read", "group": "tickets", "access": "read", "sensitive": false, "label": { "en": "Read tickets", "ru": "Чтение тикетов", "he": "קריאת כרטיסים" }, "description": { "en": "The ticket list and details (opener, panel, status, form answers) and the saved transcripts of closed tickets.", "ru": "Список и данные тикетов (автор, панель, статус, ответы формы) и сохранённые расшифровки закрытых тикетов.", "he": "רשימת הכרטיסים ופרטיהם (פותח, פאנל, סטטוס, תשובות הטופס) ותמלילים שמורים של כרטיסים סגורים." } }, { "key": "tickets:write", "group": "tickets", "access": "write", "sensitive": false, "label": { "en": "Close tickets", "ru": "Закрытие тикетов", "he": "סגירת כרטיסים" }, "description": { "en": "Close open tickets with a reason — the bot saves the transcript, logs it and notifies the opener like a staff close.", "ru": "Закрывать открытые тикеты с причиной — бот сохраняет расшифровку, пишет в лог и уведомляет автора, как при закрытии персоналом.", "he": "סגירת כרטיסים פתוחים עם סיבה — הבוט שומר תמליל, רושם ביומן ומודיע לפותח כמו בסגירה על ידי הצוות." } }, { "key": "applications:read", "group": "applications", "access": "read", "sensitive": false, "label": { "en": "Read applications", "ru": "Чтение заявок", "he": "קריאת מועמדויות" }, "description": { "en": "Application forms and submissions, including the applicants’ answers, votes and decisions.", "ru": "Формы и поданные заявки, включая ответы кандидатов, голоса и решения.", "he": "טפסי מועמדות והגשות, כולל תשובות המועמדים, הצבעות והחלטות." } }, { "key": "applications:write", "group": "applications", "access": "write", "sensitive": false, "label": { "en": "Decide applications", "ru": "Решения по заявкам", "he": "החלטה על מועמדויות" }, "description": { "en": "Accept or deny open applications. The bot gives / removes the form’s roles, DMs the applicant and updates the review like a staff decision.", "ru": "Принимать и отклонять открытые заявки. Бот выдаёт / снимает роли формы, пишет кандидату в ЛС и обновляет обсуждение, как при решении персонала.", "he": "אישור או דחייה של מועמדויות פתוחות. הבוט נותן / מסיר את תפקידי הטופס, שולח הודעה למועמד ומעדכן את הדיון כמו בהחלטת צוות." } }, { "key": "appeals:read", "group": "appeals", "access": "read", "sensitive": false, "label": { "en": "Read ban appeals", "ru": "Чтение апелляций", "he": "קריאת ערעורים" }, "description": { "en": "Ban appeals with their answers, the ban reason and the conversation (internal staff notes are never included).", "ru": "Апелляции на бан с ответами, причиной бана и перепиской (внутренние заметки персонала не передаются).", "he": "ערעורי הרחקה עם התשובות, סיבת ההרחקה והשיחה (הערות פנימיות של הצוות לעולם לא נכללות)." } }, { "key": "appeals:write", "group": "appeals", "access": "write", "sensitive": true, "label": { "en": "Decide ban appeals", "ru": "Решения по апелляциям", "he": "החלטה על ערעורים" }, "description": { "en": "Approve (unban) or reject open ban appeals with a reason; the bot unbans and DMs like a staff decision.", "ru": "Одобрять (разбанивать) или отклонять открытые апелляции с причиной; бот разбанивает и пишет в ЛС, как при решении персонала.", "he": "אישור (ביטול הרחקה) או דחייה של ערעורים פתוחים עם סיבה; הבוט מבטל את ההרחקה ושולח הודעה כמו בהחלטת צוות." }, "warning": { "en": "Approving an appeal unbans the member.", "ru": "Одобрение апелляции снимает бан с участника.", "he": "אישור ערעור מבטל את ההרחקה של החבר." } }, { "key": "moderation:read", "group": "moderation", "access": "read", "sensitive": true, "label": { "en": "Read moderation cases", "ru": "Чтение дел модерации", "he": "קריאת תיקי ניהול" }, "description": { "en": "Moderation cases (warnings, timeouts, kicks, bans…) with reasons, evidence links and moderators, and the status of API actions.", "ru": "Дела модерации (предупреждения, тайм-ауты, кики, баны…) с причинами, ссылками-доказательствами и модераторами, и статус действий через API.", "he": "תיקי ניהול (אזהרות, השתקות, הרחקות, חסימות…) עם סיבות, קישורי ראיות ומנהלים, וסטטוס פעולות API." }, "warning": { "en": "Exposes members’ moderation history.", "ru": "Открывает доступ к истории модерации участников.", "he": "חושף את היסטוריית הניהול של החברים." } }, { "key": "moderation:write", "group": "moderation", "access": "write", "sensitive": true, "label": { "en": "Moderate members", "ru": "Модерация участников", "he": "ניהול חברים" }, "description": { "en": "Warn, time out, kick, ban and unban members as the key’s creator: only while they still have the matching Discord permission, only members below their and the bot’s highest role, with a reason, at most 10 actions a minute.", "ru": "Предупреждать, давать тайм-аут, кикать, банить и разбанивать от имени создателя ключа: только пока у него есть нужное право Discord, только участников ниже его и бота по роли, с причиной, не больше 10 действий в минуту.", "he": "אזהרה, השתקה, הרחקה, חסימה וביטול חסימה בשם יוצר המפתח: רק כל עוד יש לו את הרשאת Discord המתאימה, רק לחברים מתחת לתפקיד הגבוה שלו ושל הבוט, עם סיבה, עד 10 פעולות בדקה." }, "warning": { "en": "Anyone holding this key can punish members in your name. Keep it secret and revoke it when unused.", "ru": "Любой, у кого есть этот ключ, может наказывать участников от вашего имени. Храните его в секрете и отзывайте, когда он не нужен.", "he": "כל מי שמחזיק במפתח הזה יכול להעניש חברים בשמך. שמרו אותו בסוד ובטלו אותו כשאינו בשימוש." } } ] }