{ "openapi": "3.0.3", "info": { "title": "ClanStop API", "description": "Read and write clans, members, games, game-only users, and community game servers (self-service cssrv_ keys + clan presence). See https://clanstop.com/APIs/V1/docs for the human-readable guide.", "version": "1.0.0", "contact": { "name": "ClanStop staff", "url": "https://clanstop.com" } }, "servers": [ { "url": "https://clanstop.com/APIs/V1" } ], "security": [ { "ApiKey": [], "UserToken": [] }, { "ApiKey": [], "BearerToken": [] } ], "tags": [ { "name": "Auth", "description": "Identify the caller." }, { "name": "Clans", "description": "Create, edit, dissolve clans; manage members." }, { "name": "Games", "description": "Public catalog plus write surfaces for app-owned games." }, { "name": "Game users", "description": "Provision or link player accounts on behalf of an integration." }, { "name": "Servers", "description": "Community-hosted game servers: self-service server keys (cssrv_), heartbeats, and clan presence." } ], "paths": { "/me": { "get": { "tags": [ "Auth" ], "operationId": "getMe", "summary": "Identify the player whose token authenticated the request. (scope: me:read)", "security": [ { "ApiKey": [], "UserToken": [] } ], "responses": { "200": { "description": "Player identified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Me" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/me/clans": { "get": { "tags": [ "Auth" ], "operationId": "getMyClans", "summary": "Clans this user is in, with is_owner flag. (scope: me:read)", "security": [ { "ApiKey": [], "UserToken": [] } ], "responses": { "200": { "description": "Clan list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClanSummary" } }, "meta": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/me/link-codes": { "post": { "tags": [ "Auth" ], "operationId": "mintLinkCode", "summary": "Mint a one-time link code for the authenticated user. The user types this code into a game to link an existing ClanStop account to that integration. (scope: me:read)", "security": [ { "ApiKey": [], "UserToken": [] } ], "responses": { "200": { "description": "Code minted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "ABCD1234" }, "display": { "type": "string", "example": "ABCD-1234" }, "expires_at": { "type": "integer", "format": "int64", "description": "Unix timestamp." }, "ttl": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/clans": { "get": { "tags": [ "Clans" ], "operationId": "listClans", "summary": "Paginated clans the calling app can see.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max rows (1..100). Default 25.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Skip the first N rows. Default 0.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Clan page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClanSummary" } }, "meta": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } }, "post": { "tags": [ "Clans" ], "operationId": "createClan", "summary": "Create a new clan with the authenticated user as founder. (scope: clan:create)", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClanInput" } } } }, "responses": { "200": { "description": "Clan created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "clan_id": { "type": "string", "example": "29401576424788" }, "name": { "type": "string" }, "tag": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/clans/{clan_id}": { "parameters": [ { "name": "clan_id", "in": "path", "required": true, "description": "BIGINT-as-string clan id.", "schema": { "type": "string" } } ], "get": { "tags": [ "Clans" ], "operationId": "getClan", "summary": "Full detail for one clan.", "responses": { "200": { "description": "Clan detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Clan" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } }, "patch": { "tags": [ "Clans" ], "operationId": "updateClan", "summary": "Update name, tag, or short_description on a clan you own. (scope: clan:manage)", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClanInput" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "clan_id": { "type": "string" }, "updated": { "type": "array", "items": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } }, "delete": { "tags": [ "Clans" ], "operationId": "dissolveClan", "summary": "Dissolve a clan you own. (scope: clan:dissolve)", "security": [ { "ApiKey": [], "UserToken": [] } ], "responses": { "200": { "description": "Dissolved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "clan_id": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/clans/{clan_id}/members": { "parameters": [ { "name": "clan_id", "in": "path", "required": true, "description": "Clan id.", "schema": { "type": "string" } } ], "get": { "tags": [ "Clans" ], "operationId": "listMembers", "summary": "Active members of a clan.", "responses": { "200": { "description": "Members.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClanMember" } }, "meta": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } }, "post": { "tags": [ "Clans" ], "operationId": "addMember", "summary": "Join a clan or add a member. When user_id is the caller (self-join) the outcome follows the clan recruiting policy: open/invite-auto add an active member (app_status=1), approval-required clans create a pending application (app_status=2), closed clans are rejected. When user_id is someone else (admin-add) the caller must hold clan management permission and the member is added active immediately. Banned users are rejected. (scope: clan:read (self-join) | clan:manage (admin-add))", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddMemberInput" } } } }, "responses": { "200": { "description": "Added or pending.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "clan_id": { "type": "string" }, "user_id": { "type": "string" }, "app_status": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/clans/{clan_id}/members/{user_id}": { "parameters": [ { "name": "clan_id", "in": "path", "required": true, "description": "Clan id.", "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "description": "User id.", "schema": { "type": "string" } } ], "delete": { "tags": [ "Clans" ], "operationId": "removeMember", "summary": "Kick a member or leave a clan. (scope: clan:manage)", "security": [ { "ApiKey": [], "UserToken": [] } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "clan_id": { "type": "string" }, "user_id": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } }, "patch": { "tags": [ "Clans" ], "operationId": "updateMemberRank", "summary": "Set an active member's rank. The rank must belong to the clan and may NOT be the owner rank (Permission=7) \u2014 use POST /clans/{id}/transfer to move ownership. Same bar as transfer/dissolve. (scope: clan:manage)", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberInput" } } } }, "responses": { "200": { "description": "Rank updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "clan_id": { "type": "string" }, "user_id": { "type": "string" }, "rank_id": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/clans/{clan_id}/transfer": { "parameters": [ { "name": "clan_id", "in": "path", "required": true, "description": "Clan id.", "schema": { "type": "string" } } ], "post": { "tags": [ "Clans" ], "operationId": "transferClan", "summary": "Transfer ownership to another user. (scope: clan:manage)", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferClanInput" } } } }, "responses": { "200": { "description": "Transferred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "clan_id": { "type": "string" }, "new_owner_id": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/games": { "get": { "tags": [ "Games" ], "operationId": "listGames", "summary": "Public catalog of games. Use for clan-creation game tags.", "responses": { "200": { "description": "Games.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GameSummary" } }, "meta": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/games/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Lowercase ShortName from /games.", "schema": { "type": "string" } } ], "get": { "tags": [ "Games" ], "operationId": "getGame", "summary": "Full game metadata including the writable Phase 8 fields.", "responses": { "200": { "description": "Game.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Game" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } }, "patch": { "tags": [ "Games" ], "operationId": "updateGame", "summary": "Update metadata (name, short_name, about, store_page_url, dev_page_url). Caller must be the assigned owner. (scope: game:manage (and you must own the row))", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGameInput" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Game" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/games/{slug}/online": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Game slug.", "schema": { "type": "string" } } ], "post": { "tags": [ "Games" ], "operationId": "reportOnline", "summary": "Lightweight current_online heartbeat for a game your app owns. (scope: game:manage (and you must own the row))", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnlineInput" } } } }, "responses": { "200": { "description": "Bumped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "current_online": { "type": "integer" }, "online_reported_at": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/game-users": { "post": { "tags": [ "Game users" ], "operationId": "provisionGameUser", "summary": "Provision or link a player account. Optional `code` field switches to the link flow.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GameUserInput" } } } }, "responses": { "200": { "description": "Provisioned or linked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "user_id": { "type": "string" }, "existing": { "type": "boolean" }, "is_game_only": { "type": "boolean" }, "token": { "type": "string", "nullable": true }, "claim_token": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/games/{slug}/servers": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Game slug.", "schema": { "type": "string" } } ], "get": { "tags": [ "Servers" ], "operationId": "listGameServers", "summary": "Public server browser for a game \u2014 active community servers, most-recently-online first.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "Servers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "server_id": { "type": "string" }, "name": { "type": "string" }, "host_note": { "type": "string", "nullable": true }, "current_online": { "type": "integer", "nullable": true }, "online_reported_at": { "type": "integer", "nullable": true }, "tick_rate": { "type": "number", "nullable": true }, "is_active_now": { "type": "boolean" }, "created_at": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } }, "post": { "tags": [ "Servers" ], "operationId": "registerServer", "summary": "Register a community game server and receive a server key (cssrv_\u2026, shown once). The host account must have a verified email and may hold at most 5 active server keys. (scope: server:manage)", "security": [ { "ApiKey": [], "UserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120, "example": "Bob's 24/7" }, "host_note": { "type": "string", "maxLength": 255, "nullable": true, "example": "us-east, modded" } } } } } }, "responses": { "200": { "description": "Server registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "server_id": { "type": "string" }, "game_id": { "type": "integer" }, "name": { "type": "string" }, "api_key": { "type": "string", "description": "cssrv_\u2026 \u2014 shown only once." }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit_per_min": { "type": "integer" }, "daily_quota": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/games/{slug}/servers/{server_id}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Game slug.", "schema": { "type": "string" } }, { "name": "server_id", "in": "path", "required": true, "description": "Server id.", "schema": { "type": "string" } } ], "delete": { "tags": [ "Servers" ], "operationId": "deleteServer", "summary": "Revoke a server key immediately. Must be the host who registered it. Players, their tokens, and clan presence survive (game-scoped). (scope: server:manage (and you must be the server owner))", "security": [ { "ApiKey": [], "UserToken": [] } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "server_id": { "type": "string" }, "status": { "type": "string", "enum": [ "revoked" ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/servers/{server_id}/heartbeat": { "parameters": [ { "name": "server_id", "in": "path", "required": true, "description": "Server id; must match the calling cssrv_ key.", "schema": { "type": "string" } } ], "post": { "tags": [ "Servers" ], "operationId": "serverHeartbeat", "summary": "Per-server heartbeat. Authenticated with the server key (cssrv_) as X-API-Key, no user token. Reports who is online; the server derives clan presence and stamps its own count + tick rate.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_online" ], "properties": { "active_user_ids": { "type": "array", "items": { "type": "string" }, "description": "ClanStop user ids online now. Max 500 per call." }, "current_online": { "type": "integer", "minimum": 0 }, "tick_rate": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1000 } } } } } }, "responses": { "200": { "description": "Recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "server_id": { "type": "string" }, "current_online": { "type": "integer" }, "clans_touched": { "type": "integer" }, "reported_at": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/clans/{clan_id}/servers": { "parameters": [ { "name": "clan_id", "in": "path", "required": true, "description": "Clan id.", "schema": { "type": "string" } } ], "get": { "tags": [ "Servers" ], "operationId": "listClanServers", "summary": "Servers a clan plays on, most-recently-seen first. Honors clan visibility (a key whose app cannot see the clan gets 404).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "Servers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "server_id": { "type": "string" }, "name": { "type": "string" }, "last_seen_at": { "type": "integer" }, "is_active_now": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/Validation" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimit" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Per-app key. Sent on every call." }, "UserToken": { "type": "apiKey", "in": "header", "name": "X-API-Token", "description": "Per-user token. Required for user-scoped endpoints. Recommended over Authorization: Bearer because many shared-host setups strip Authorization." }, "BearerToken": { "type": "http", "scheme": "bearer", "description": "Alternative to X-API-Token; standard REST. Pass the csu_\u2026 as the bearer credential." } }, "schemas": { "EnvelopeSuccess": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object" }, "meta": { "type": "object", "nullable": true } } }, "EnvelopeError": { "type": "object", "required": [ "status", "error" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "nullable": true } } } } }, "Me": { "type": "object", "properties": { "user_id": { "type": "string", "description": "BIGINT as string." }, "display_name": { "type": "string" }, "joined_date": { "type": "integer", "description": "Unix timestamp." } } }, "ClanSummary": { "type": "object", "properties": { "clan_id": { "type": "string" }, "name": { "type": "string" }, "tag": { "type": "string" }, "short_description": { "type": "string", "nullable": true } } }, "Clan": { "allOf": [ { "$ref": "#/components/schemas/ClanSummary" }, { "type": "object", "properties": { "games": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" } }, "created": { "type": "integer" }, "is_owner": { "type": "boolean", "nullable": true }, "recruiting": { "type": "integer", "description": "Join policy 1..5 (0 if unset). 1=apply/approval, 2=open, 3=invite-only auto, 4=invite-only approval, 5=closed." }, "join_policy": { "type": "string", "enum": [ "open", "approval", "invite_auto", "invite_approval", "closed" ], "description": "Human-readable form of recruiting." } } } ] }, "ClanMember": { "type": "object", "properties": { "user_id": { "type": "string" }, "display_name": { "type": "string" }, "is_owner": { "type": "boolean" }, "joined": { "type": "integer" } } }, "GameSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "short_name": { "type": "string" }, "slug": { "type": "string" }, "image_url": { "type": "string" } } }, "Game": { "allOf": [ { "$ref": "#/components/schemas/GameSummary" }, { "type": "object", "properties": { "about": { "type": "string", "nullable": true }, "store_page_url": { "type": "string", "nullable": true }, "dev_page_url": { "type": "string", "nullable": true }, "current_online": { "type": "integer", "nullable": true }, "online_reported_at": { "type": "integer", "nullable": true }, "owned_by_app_id": { "type": "integer", "nullable": true }, "stable_identity": { "type": "boolean", "description": "Whether the game exposes a stable, game-wide player id (drives the server mod provisioning branch)." } } } ] }, "CreateClanInput": { "type": "object", "required": [ "name", "tag", "games", "platforms" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "tag": { "type": "string", "minLength": 3, "maxLength": 8 }, "short_description": { "type": "string", "maxLength": 1500 }, "games": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "platforms": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "recruiting": { "type": "integer", "minimum": 1, "maximum": 5 } } }, "UpdateClanInput": { "type": "object", "properties": { "name": { "type": "string" }, "tag": { "type": "string" }, "short_description": { "type": "string" }, "recruiting": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Join policy: 1=apply/approval, 2=open, 3=invite-only auto-approve, 4=invite-only approval, 5=closed." } } }, "AddMemberInput": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "The user to add. When equal to the caller it is a self-join governed by the clan recruiting policy; when different it is an admin-add (requires clan management permission, adds active immediately)." } } }, "TransferClanInput": { "type": "object", "required": [ "new_owner_user_id" ], "properties": { "new_owner_user_id": { "type": "string" } } }, "UpdateMemberInput": { "type": "object", "required": [ "rank_id" ], "properties": { "rank_id": { "type": "string", "description": "A CustomRanks.ID belonging to the clan. Cannot be the owner rank \u2014 use the transfer endpoint to move ownership." } } }, "UpdateGameInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "short_name": { "type": "string", "minLength": 2, "maxLength": 16 }, "about": { "type": "string", "maxLength": 8000 }, "store_page_url": { "type": "string", "maxLength": 500 }, "dev_page_url": { "type": "string", "maxLength": 500 } } }, "OnlineInput": { "type": "object", "required": [ "current_online" ], "properties": { "current_online": { "type": "integer", "minimum": 0 } } }, "GameUserInput": { "type": "object", "required": [ "external_user_id" ], "properties": { "external_user_id": { "type": "string", "description": "Game-side id, e.g. steamid:76561\u2026" }, "display_name": { "type": "string", "nullable": true }, "scopes": { "type": "string", "description": "CSV of scopes to grant the issued token." }, "code": { "type": "string", "description": "Optional 8-char OTP from /gameprofiles. Present = link existing user instead of provisioning new." } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid auth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeError" } } } }, "Forbidden": { "description": "Scope or ownership check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeError" } } } }, "NotFound": { "description": "Target does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeError" } } } }, "Validation": { "description": "Input fails validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeError" } } } }, "Conflict": { "description": "State conflict (already member, reserved name, etc).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeError" } } } }, "RateLimit": { "description": "Rate-limited or daily-quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeError" } } } } } } }