{ "openapi": "3.1.0", "info": { "title": "Gamer Sites API — reviewed core subset", "version": "82cf658", "description": "Source-grounded curated subset reviewed 2026-10-24. Not an exhaustive API description or a grant of access. Reserved example server prevents accidental calls to a live environment. Configure only the existing approved API origin. No live action console is included. Existing public API origin: https://aero.gamersites.gg. The documentation website is a separate origin and does not share its session. No generic bearer token is accepted by the community-session routes.", "x-source-revision": "82cf65879b5fa09800bc0d4fc5e31557332cabbe" }, "servers": [ { "url": "https://api.example.invalid", "description": "Placeholder only; use your existing authorized API origin." } ], "paths": { "/api/v1/me": { "get": { "operationId": "getAccount", "summary": "Read current GS account", "description": "Existing session; do not expose private response in public docs.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "401": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "403": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "404": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "409": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "429": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "503": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } } } }, "/api/v1/me/preferences": { "post": { "operationId": "savePreferences", "summary": "Change own marketing preference", "description": "Existing session plus exact Origin and CSRF.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "401": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "403": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "404": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "409": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "429": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "503": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketing_opt_in": { "type": "boolean" } }, "required": [ "marketing_opt_in" ], "additionalProperties": false } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Current session value from /api/v1/me." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly equal configured API origin. Browser sets this automatically in the existing same-origin app." } ] } }, "/api/v1/communities/{community}/overview": { "get": { "operationId": "getCommunityOverview", "summary": "Read authorized community overview", "description": "Requires any of community.upgrades.view, community.aero.view, community.chat.view.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Community" } } } }, "400": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "401": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "403": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "404": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "409": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "429": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "503": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } } }, "parameters": [ { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "/api/v1/communities/{community}/aero": { "get": { "operationId": "readAero", "summary": "Read Aero settings and readiness", "description": "community.aero.view; verified current identity/guild binding and Discord management authority.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AeroEnvelope" } } } }, "400": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "401": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "403": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "404": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "409": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "429": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "503": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } } }, "parameters": [ { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "/api/v1/communities/{community}/aero/settings": { "post": { "operationId": "saveAeroSettings", "summary": "Patch Aero settings at current version", "description": "community.aero.view AND community.aero.manage, Origin/CSRF, current Discord management authority. A timeout/503 is not proof of rollback.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AeroEnvelope" } } } }, "400": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "401": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "403": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "404": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "409": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "429": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "503": { "description": "Request failed; base Aero can instead return AeroEnvelope with code/outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settings": { "$ref": "#/components/schemas/AeroSettingsPatch" } }, "required": [ "expected_version", "settings" ], "additionalProperties": false } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Current session value from /api/v1/me." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly equal configured API origin. Browser sets this automatically in the existing same-origin app." } ] }, "parameters": [ { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "components": { "securitySchemes": { "gsSession": { "type": "apiKey", "in": "cookie", "name": "__Host-gs_session", "description": "Existing secure HttpOnly GS session. Not a generic Bearer token. Browser calls must run in the already signed-in same-origin app." } }, "schemas": { "MessageError": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "Profile": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string" } }, "admin_communities": { "type": "array", "items": { "type": "string" } }, "support_group": { "type": "string" }, "marketing_segments": { "type": "array", "items": { "type": "string" } }, "marketing_opt_in": { "type": "boolean" } }, "required": [ "roles", "admin_communities", "support_group", "marketing_segments", "marketing_opt_in" ] }, "Me": { "type": "object", "properties": { "user": { "type": "object", "description": "Existing current-user projection from the pinned identity service; treat as personal data." }, "csrf": { "type": "string", "description": "Session CSRF value; keep private and in memory." }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "community_id": { "type": "string" }, "community_name": { "type": "string" }, "permissions": { "type": "string", "description": "JSON-encoded string array in this API version." } }, "required": [ "community_id", "community_name", "permissions" ] } }, "profile": { "$ref": "#/components/schemas/Profile" } }, "required": [ "user", "csrf", "memberships", "profile" ] }, "Community": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "site_url": { "type": "string" }, "guild_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "id", "name", "site_url", "guild_id" ] }, "AeroSettingsPatch": { "type": "object", "properties": { "welcome_enabled": { "type": "boolean" }, "gamer_sites_enabled": { "type": "boolean" }, "palworld_sticky_enabled": { "type": "boolean" }, "palworld_show_player_names": { "type": "boolean" }, "windrose_sticky_enabled": { "type": "boolean" }, "windrose_show_player_names": { "type": "boolean" }, "conan_sticky_enabled": { "type": "boolean" }, "conan_show_player_names": { "type": "boolean" }, "dragonwilds_sticky_enabled": { "type": "boolean" }, "dragonwilds_show_player_names": { "type": "boolean" }, "announcement_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "live_alert_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "schedule_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "welcome_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "rules_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "intro_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "roles_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "palworld_status_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "windrose_status_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "conan_status_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "dragonwilds_status_channel_id": { "description": "Empty/null clears; otherwise a positive Discord ID below 2^63. Responses normalize to string.", "oneOf": [ { "type": "string", "pattern": "^([0-9]+)?$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "welcome_title": { "type": "string", "maxLength": 256, "description": "NUL forbidden." }, "welcome_message": { "type": "string", "maxLength": 4096, "description": "NUL forbidden." }, "welcome_footer": { "type": "string", "maxLength": 2048, "description": "NUL forbidden." }, "website_url": { "type": "string", "maxLength": 2048, "description": "Nonempty value must be HTTPS without credentials; NUL forbidden." }, "welcome_background_url": { "type": "string", "maxLength": 2048, "description": "Nonempty value must be HTTPS without credentials; NUL forbidden." }, "gamer_sites_site_url": { "type": "string", "maxLength": 2048, "description": "Nonempty value must be HTTPS without credentials; NUL forbidden." }, "palworld_sticky_delay_seconds": { "type": "integer", "minimum": 5, "maximum": 300 }, "windrose_sticky_delay_seconds": { "type": "integer", "minimum": 5, "maximum": 300 }, "conan_sticky_delay_seconds": { "type": "integer", "minimum": 5, "maximum": 300 }, "dragonwilds_sticky_delay_seconds": { "type": "integer", "minimum": 5, "maximum": 300 }, "welcome_mode": { "type": "string", "enum": [ "embed", "image" ] }, "welcome_accent_color": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "game_admin_role_ids": { "type": "array", "maxItems": 20, "items": { "oneOf": [ { "type": "string", "pattern": "^[0-9]+$" }, { "type": "integer", "minimum": 1 } ] }, "description": "Each ID must be positive and below 2^63; use strings to preserve precision." } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "AeroEnvelope": { "type": "object", "properties": { "community": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "guild_id": { "type": "string" } }, "required": [ "id", "name", "guild_id" ] }, "readiness": { "type": "object", "properties": { "api_reachable": { "type": "boolean" }, "relay_connected": { "type": "boolean" }, "discord_ready": { "type": [ "boolean", "null" ] }, "guild_connected": { "type": [ "boolean", "null" ] }, "guild_name": { "type": [ "string", "null" ] }, "checked_at": { "type": "string", "format": "date-time" } }, "required": [ "api_reachable", "relay_connected", "discord_ready", "guild_connected", "guild_name", "checked_at" ] }, "settings": { "oneOf": [ { "type": "object", "description": "Complete public settings using AeroSettingsPatch property definitions; every editable key is returned." }, { "type": "null" } ] }, "version": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "can_edit": { "type": "boolean" }, "outcome": { "type": "string", "enum": [ "loaded", "saved", "conflict", "unavailable" ] }, "code": { "type": "string" } }, "required": [ "community", "readiness", "settings", "version", "channels", "roles", "can_edit", "outcome" ] } } }, "x-reviewed-at": "2026-10-24", "x-scope": "Core integration subset; full source inventory and module boundaries are in the readable documentation.", "security": [ { "gsSession": [] } ], "externalDocs": { "url": "https://gamersites.gg/developers/", "description": "Public human reference; does not grant access." } }