{ "openapi": "3.1.1", "info": { "title": "Community Support Player API", "description": "HTTPS/JSON API for identifying players, creating support tickets, continuing conversations, and polling the in-game inbox.", "version": "v1" }, "servers": [ { "url": "https://community.game-mode.dev/" } ], "paths": { "/api/v1/player/identify": { "post": { "tags": [ "Player identity" ], "summary": "Identify a player installation", "description": "Registers or refreshes an installation, records optional game context, and returns a rotated player access token.", "operationId": "IdentifyPlayer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IdentifyRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/IdentifyRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IdentifyResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IdentifyResponse" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProjectUnavailableResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUnavailableResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProjectUnavailableResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/tickets": { "post": { "tags": [ "Tickets" ], "summary": "Create a support ticket", "description": "Creates a ticket with its first player message. Requires the player access token in the Authorization: Bearer header.", "operationId": "CreateTicket", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicketRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateTicketRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateTicketRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateTicketResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicketResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateTicketResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "PlayerBearer": [ ] } ] } }, "/api/v1/player/tickets": { "get": { "tags": [ "Tickets" ], "summary": "List the player's tickets", "description": "Returns up to 100 tickets for the authenticated player, ordered by latest activity.", "operationId": "ListPlayerTickets", "parameters": [ { "name": "projectPublicKey", "in": "query", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PlayerTicketsResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PlayerTicketsResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PlayerTicketsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "PlayerBearer": [ ] } ] } }, "/api/v1/tickets/{ticketId}": { "get": { "tags": [ "Tickets" ], "summary": "Get a ticket conversation", "description": "Returns the public conversation for one player-owned ticket and marks admin replies as read by the player.", "operationId": "GetTicket", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/TicketDetailsResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TicketDetailsResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TicketDetailsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "PlayerBearer": [ ] } ] } }, "/api/v1/tickets/{ticketId}/messages": { "post": { "tags": [ "Tickets" ], "summary": "Reply to a ticket", "description": "Adds a player reply to an open ticket and returns it to the team's attention queue.", "operationId": "AddTicketMessage", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTicketMessageRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddTicketMessageRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AddTicketMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/AddTicketMessageResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AddTicketMessageResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddTicketMessageResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "PlayerBearer": [ ] } ] } }, "/api/v1/player/inbox": { "get": { "tags": [ "Inbox" ], "summary": "Poll the in-game inbox", "description": "Returns recent messages for the authenticated player and a suggested delay before the next poll.", "operationId": "GetPlayerInbox", "parameters": [ { "name": "projectPublicKey", "in": "query", "required": true, "schema": { "maxLength": 80, "type": "string" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PlayerInboxResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PlayerInboxResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PlayerInboxResponse" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "PlayerBearer": [ ] } ] } }, "/api/v1/player/inbox/{messageId}/read": { "post": { "tags": [ "Inbox" ], "summary": "Mark an inbox message as read", "description": "Marks one player-owned inbox message as read. Repeating the request is safe.", "operationId": "MarkInboxMessageRead", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/MarkInboxReadResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/MarkInboxReadResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/MarkInboxReadResponse" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "PlayerBearer": [ ] } ] } } }, "components": { "schemas": { "AddTicketMessageRequest": { "required": [ "message" ], "type": "object", "properties": { "message": { "maxLength": 4000, "minLength": 1, "type": "string" } } }, "AddTicketMessageResponse": { "required": [ "messageId", "status", "createdAt" ], "type": "object", "properties": { "messageId": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CreateTicketRequest": { "required": [ "projectPublicKey", "type", "subject", "message" ], "type": "object", "properties": { "projectPublicKey": { "maxLength": 80, "type": "string" }, "type": { "maxLength": 30, "type": "string" }, "subject": { "maxLength": 120, "minLength": 1, "type": "string" }, "message": { "maxLength": 4000, "minLength": 1, "type": "string" }, "context": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlayerContextRequest" } ] } } }, "CreateTicketResponse": { "required": [ "ticketId", "status", "createdAt" ], "type": "object", "properties": { "ticketId": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "IdentifyRequest": { "required": [ "projectPublicKey", "installationId" ], "type": "object", "properties": { "projectPublicKey": { "maxLength": 80, "type": "string" }, "userId": { "maxLength": 200, "type": [ "null", "string" ] }, "installationId": { "maxLength": 128, "minLength": 8, "type": "string" }, "sessionId": { "maxLength": 128, "type": [ "null", "string" ] }, "context": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlayerContextRequest" } ] } } }, "IdentifyResponse": { "required": [ "playerId", "playerAccessToken", "serverTime" ], "type": "object", "properties": { "playerId": { "type": "string" }, "playerAccessToken": { "type": "string" }, "serverTime": { "type": "string", "format": "date-time" } } }, "InboxMessageResponse": { "required": [ "id", "type", "ticketId", "title", "body", "createdAt", "readAt" ], "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "ticketId": { "type": [ "null", "string" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "readAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "MarkInboxReadResponse": { "required": [ "ok", "readAt" ], "type": "object", "properties": { "ok": { "type": "boolean" }, "readAt": { "type": "string", "format": "date-time" } } }, "PlayerContextRequest": { "type": "object", "properties": { "appVersion": { "maxLength": 50, "type": [ "null", "string" ] }, "buildNumber": { "maxLength": 50, "type": [ "null", "string" ] }, "platform": { "maxLength": 50, "type": [ "null", "string" ] }, "locale": { "maxLength": 30, "type": [ "null", "string" ] }, "deviceModel": { "maxLength": 200, "type": [ "null", "string" ] }, "osVersion": { "maxLength": 100, "type": [ "null", "string" ] } } }, "PlayerInboxResponse": { "required": [ "messages", "nextPollAfterSeconds" ], "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InboxMessageResponse" } }, "nextPollAfterSeconds": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "PlayerTicketsResponse": { "required": [ "tickets" ], "type": "object", "properties": { "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/TicketSummaryResponse" } } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ProjectUnavailableError": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "ProjectUnavailableResponse": { "required": [ "error", "requestId" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ProjectUnavailableError" }, "requestId": { "type": "string" } } }, "TicketDetailsResponse": { "required": [ "id", "type", "status", "subject", "messages" ], "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/TicketMessageResponse" } } } }, "TicketMessageResponse": { "required": [ "id", "authorType", "message", "createdAt" ], "type": "object", "properties": { "id": { "type": "string" }, "authorType": { "type": "string" }, "message": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "TicketSummaryResponse": { "required": [ "id", "type", "status", "subject", "lastMessagePreview", "lastMessageAt", "unreadCount" ], "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "lastMessagePreview": { "type": [ "null", "string" ] }, "lastMessageAt": { "type": [ "null", "string" ], "format": "date-time" }, "unreadCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ValidationProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "securitySchemes": { "PlayerBearer": { "type": "http", "description": "Player token returned by POST /api/v1/player/identify.", "scheme": "bearer", "bearerFormat": "opaque player access token" } } }, "tags": [ { "name": "Player identity" }, { "name": "Tickets" }, { "name": "Inbox" } ] }