{ "openapi": "3.0.3", "paths": { "/api/account": { "delete": { "description": "Cascading deletion of the user's data via the registered cleanup pipeline. Requires fresh auth (auth_time within the last 5 minutes) and `confirmText: \"DELETE\"`.", "summary": "GDPR Article 17: delete the current user's account", "tags": [ "account" ], "parameters": [], "operationId": "account.deleteAccount", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmText": { "type": "string", "enum": [ "DELETE" ], "description": "Must be the exact string 'DELETE' to confirm intent" } }, "required": [ "confirmText" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "uid": { "type": "string" }, "stepsCompleted": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": [ "success", "uid", "stepsCompleted", "errors", "message" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/account/purge": { "post": { "description": "HMAC-authenticated via header. Picks up `accountDeletions` docs older than 30 days and finishes their cascade.", "summary": "Cron-only: resume stale 30-day account deletions", "tags": [ "account" ], "parameters": [], "operationId": "account.purge", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "completedCount": { "type": "integer", "minimum": 0 }, "completedUids": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "completedCount", "completedUids" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/agents/register": { "post": { "summary": "Register a new agent (returns API key + claim URL)", "tags": [ "agents" ], "parameters": [], "operationId": "agents.register", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 50, "pattern": "^[a-zA-Z0-9\\s\\-_]+$" }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/agents/me": { "get": { "summary": "Get the authenticated agent's profile", "tags": [ "agents" ], "parameters": [], "operationId": "agents.me", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "summary": "Update the authenticated agent's profile", "tags": [ "agents" ], "parameters": [], "operationId": "agents.mePatch", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 50, "pattern": "^[a-zA-Z0-9\\s\\-_]+$" }, "description": { "type": "string", "maxLength": 500, "nullable": true }, "avatarUrl": { "type": "string", "format": "uri", "nullable": true }, "visibility": { "type": "object", "properties": { "isPublic": { "type": "boolean" }, "showOwner": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/agents/user": { "get": { "summary": "List agents owned by the authenticated user", "tags": [ "agents" ], "parameters": [], "operationId": "agents.user", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/agents/claim/{token}": { "get": { "summary": "Get info about an agent pending claim", "tags": [ "agents" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "agents.claimGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "summary": "Claim an agent (link to authenticated user)", "tags": [ "agents" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "agents.claimPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/analytics/summary": { "get": { "summary": "Public aggregate analytics summary (cached snapshot)", "tags": [ "analytics" ], "parameters": [], "operationId": "analytics.summary", "responses": { "200": { "description": "AnalyticsSummary — see lib/analytics-snapshot-compute.ts", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "AnalyticsSummary — see lib/analytics-snapshot-compute.ts" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/auth/resolve-email": { "post": { "description": "Used during login to resolve secondary/alias emails to the canonical primary email. Public endpoint — does not require authentication. Returns 200 even when no account is found, to avoid leaking which emails are registered.", "summary": "Resolve an email (or alias) to its primary account email", "tags": [ "auth" ], "parameters": [], "operationId": "auth.resolveEmail", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "Email to resolve. Case-insensitive; whitespace trimmed server-side." } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "primaryEmail": { "type": "string" }, "isAlias": { "type": "boolean" } }, "required": [ "primaryEmail", "isAlias" ] }, { "type": "object", "properties": { "primaryEmail": { "type": "string", "format": "null", "nullable": true }, "isAlias": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" } }, "required": [ "primaryEmail", "isAlias", "message" ] } ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/auth/change-primary-email": { "post": { "summary": "Promote an additional verified email to primary", "tags": [ "auth" ], "parameters": [], "operationId": "auth.changePrimaryEmail", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "newPrimaryEmail": { "type": "string", "minLength": 1 } }, "required": [ "newPrimaryEmail" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } }, "required": [ "success" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/auth/remove-email": { "post": { "summary": "Remove an additional email from the account", "tags": [ "auth" ], "parameters": [], "operationId": "auth.removeEmail", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/auth/send-email-verification": { "post": { "summary": "Send a verification email for an additional email", "tags": [ "auth" ], "parameters": [], "operationId": "auth.sendEmailVerification", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } }, "required": [ "success" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/auth/verify-email": { "get": { "description": "GET handler triggered by emailed magic link. On success/failure it redirects (302) to /profile with success/error query params; clients should follow the redirect rather than read the body.", "summary": "Verify an email via tokenized link (redirects to /profile)", "tags": [ "auth" ], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "auth.verifyEmail", "responses": { "302": { "description": "Redirect to /profile with status query params", "content": { "application/json": { "schema": { "description": "Redirect to /profile with status query params", "nullable": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/badges/definitions": { "get": { "summary": "Public list of badge definitions", "tags": [ "badges" ], "parameters": [], "operationId": "badges.definitions", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/badges/awards": { "post": { "summary": "Recompute and persist badge awards for the current user", "tags": [ "badges" ], "parameters": [], "operationId": "badges.awards", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/certificate/mine": { "get": { "summary": "List LinkedIn certificates issued to the signed-in user", "tags": [ "certificate" ], "parameters": [], "operationId": "certificate.mine", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/certificate/claim": { "post": { "summary": "Claim a Cursor Boston merged-PR certificate", "tags": [ "certificate" ], "parameters": [], "operationId": "certificate.claim", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cfp/send-edu-code": { "post": { "summary": "Send a 6-digit verification code to a .edu email", "tags": [ "cfp" ], "parameters": [], "operationId": "cfp.sendEduCode", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cfp/verify-edu-code": { "post": { "summary": "Verify the .edu code and attach the email + eduBadge", "tags": [ "cfp" ], "parameters": [], "operationId": "cfp.verifyEduCode", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "email", "code" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/post": { "post": { "description": "Creates a top-level post in the community feed. Authentication required. Rate-limited to 10 requests per minute per client.", "summary": "Create a community post", "tags": [ "community" ], "parameters": [], "operationId": "community.createPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 100, "maxLength": 500 } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" } }, "required": [ "messageId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/feed": { "get": { "description": "Returns top-level messages or replies after applying hidden-message, suspended-author, and viewer block filters.", "summary": "List visible community feed messages", "tags": [ "community" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "parentId", "in": "query", "description": "Optional parent message id. Omit for top-level feed messages.", "schema": { "type": "string", "minLength": 1 } } ], "operationId": "community.feed", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "authorId": { "type": "string" }, "authorName": { "type": "string" }, "authorPhoto": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "parentId": { "type": "string" }, "repostOf": { "type": "object", "properties": { "originalId": { "type": "string" }, "originalAuthorId": { "type": "string" }, "originalAuthorName": { "type": "string" }, "originalContent": { "type": "string" } }, "required": [ "originalId", "originalAuthorId", "originalAuthorName", "originalContent" ] }, "likeCount": { "type": "number" }, "dislikeCount": { "type": "number" }, "replyCount": { "type": "number" }, "repostCount": { "type": "number" }, "bookmarkCount": { "type": "number" } }, "required": [ "id", "content", "authorId", "authorName", "authorPhoto", "createdAt" ] } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "messages", "nextCursor", "hasMore" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/community/reply": { "post": { "summary": "Reply to a community post", "tags": [ "community" ], "parameters": [], "operationId": "community.createReply", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "parentId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 100, "maxLength": 500 } }, "required": [ "parentId", "content" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "replyId": { "type": "string" } }, "required": [ "replyId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/repost": { "post": { "summary": "Repost a community message with optional commentary", "tags": [ "community" ], "parameters": [], "operationId": "community.createRepost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "originalId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 100, "maxLength": 500 } }, "required": [ "originalId", "content" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "repostId": { "type": "string" } }, "required": [ "repostId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/reaction": { "post": { "summary": "Add / remove / switch a like or dislike on a message", "tags": [ "community" ], "parameters": [], "operationId": "community.reaction", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "like", "dislike" ] } }, "required": [ "messageId", "type" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "added", "removed", "switched" ] }, "type": { "type": "string", "enum": [ "like", "dislike" ] }, "previousType": { "type": "string", "enum": [ "like", "dislike" ] } }, "required": [ "action" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/my-reactions": { "get": { "summary": "Get the current user's reactions for a batch of messages", "tags": [ "community" ], "parameters": [ { "name": "messageIds", "in": "query", "description": "Comma-separated message ids, up to 60", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "community.myReactions", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "reactions": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "like", "dislike" ] } } }, "required": [ "reactions" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/delete": { "post": { "summary": "Delete the current user's own community message", "tags": [ "community" ], "parameters": [], "operationId": "community.deletePost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string", "minLength": 1 } }, "required": [ "messageId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/block": { "post": { "summary": "Block another user", "tags": [ "community" ], "parameters": [], "operationId": "community.block", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetUid": { "type": "string", "minLength": 1 } }, "required": [ "targetUid" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "summary": "Unblock another user", "tags": [ "community" ], "parameters": [ { "name": "targetUid", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "community.unblock", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/report": { "post": { "summary": "Report a message for moderation", "tags": [ "community" ], "parameters": [], "operationId": "community.report", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetMessageId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "enum": [ "spam", "harassment", "hate", "self-harm", "other" ] }, "notes": { "type": "string" } }, "required": [ "targetMessageId", "reason" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "reportId": { "type": "string" } }, "required": [ "success", "reportId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/community/moderate": { "get": { "summary": "Admin: list community reports (paginated)", "tags": [ "community" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter status; default 'open', or 'all'", "schema": { "type": "string" } } ], "operationId": "community.moderateList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "reports", "nextCursor", "hasMore" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Admin: act on a community report (dismiss / hide / suspend)", "tags": [ "community" ], "parameters": [], "operationId": "community.moderateAction", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "dismiss", "hide", "suspend" ] } }, "required": [ "reportId", "action" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "action": { "type": "string" }, "reportId": { "type": "string" } }, "required": [ "success", "action", "reportId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cookbook/entries": { "get": { "summary": "List cookbook entries (paginated, filterable, searchable)", "tags": [ "cookbook" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Cookbook category filter", "schema": { "type": "string" } }, { "name": "worksWith", "in": "query", "description": "Tool/language tag filter", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search across title/description/tags", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort mode; defaults to 'newest' (or when search is set)", "schema": { "type": "string", "enum": [ "newest", "oldest", "top" ] } } ], "operationId": "cookbook.entries", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "promptContent": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "worksWith": { "type": "array", "items": { "type": "string" } }, "authorId": { "type": "string" }, "authorDisplayName": { "type": "string" }, "createdAt": { "type": "string" }, "upCount": { "type": "integer", "minimum": 0 }, "downCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "title", "description", "promptContent", "category", "tags", "worksWith", "authorId", "authorDisplayName", "createdAt", "upCount", "downCount" ], "additionalProperties": true } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "entries", "nextCursor", "hasMore" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "summary": "Submit a new cookbook entry", "tags": [ "cookbook" ], "parameters": [], "operationId": "cookbook.createEntry", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "promptContent": { "type": "string", "minLength": 1, "maxLength": 10000 }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "worksWith": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "description", "promptContent" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "promptContent": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "worksWith": { "type": "array", "items": { "type": "string" } }, "authorId": { "type": "string" }, "authorDisplayName": { "type": "string" }, "createdAt": { "type": "string" }, "upCount": { "type": "integer", "minimum": 0 }, "downCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "title", "description", "promptContent", "category", "tags", "worksWith", "authorId", "authorDisplayName", "createdAt", "upCount", "downCount" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cookbook/vote": { "post": { "summary": "Up- or down-vote a cookbook entry (toggle / switch supported)", "tags": [ "cookbook" ], "parameters": [], "operationId": "cookbook.vote", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "entryId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "entryId", "type" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "added", "removed", "switched" ] }, "type": { "type": "string", "enum": [ "up", "down" ] }, "previousType": { "type": "string", "enum": [ "up", "down" ] }, "upCount": { "type": "integer", "minimum": 0 }, "downCount": { "type": "integer", "minimum": 0 } }, "required": [ "action", "type", "upCount", "downCount" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "get": { "summary": "Get the current user's vote map across all cookbook entries", "tags": [ "cookbook" ], "parameters": [], "operationId": "cookbook.voteList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "userVotes": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "userVotes" ] } } } } } } }, "/api/cursor/connect": { "post": { "summary": "Validate and store the current user's Cursor API key", "tags": [ "cursor" ], "parameters": [], "operationId": "cursor.connect", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1 }, "monthlyCapUsd": { "type": "number", "enum": [ 0, 5, 25, 100 ] } }, "required": [ "apiKey", "monthlyCapUsd" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "fingerprint": { "type": "string" }, "defaultModel": { "type": "string" } }, "required": [ "ok", "fingerprint" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/disconnect": { "post": { "summary": "Disconnect the current user's Cursor API key", "tags": [ "cursor" ], "parameters": [], "operationId": "cursor.disconnect", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "disconnected": { "type": "boolean", "enum": [ true ] } }, "required": [ "disconnected" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs": { "post": { "summary": "Launch a Cursor Cloud Agent to propose contribution PR ideas", "tags": [ "cursor" ], "parameters": [], "operationId": "cursor.launchIdeaRun", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "202": { "description": "202", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "get": { "summary": "List recent Cursor PR idea runs for the current user", "tags": [ "cursor" ], "parameters": [], "operationId": "cursor.listIdeaRuns", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } } }, "required": [ "ok", "runs" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/github-issues": { "get": { "summary": "List open GitHub issues for PR Studio", "tags": [ "cursor" ], "parameters": [], "operationId": "cursor.listGithubIssues", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "labels": { "type": "array", "items": { "type": "string" } }, "body": { "type": "string", "nullable": true }, "comments": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "number", "title", "url", "labels", "body", "comments", "updatedAt" ] } } }, "required": [ "ok", "issues" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}": { "get": { "summary": "Get and refresh a Cursor PR idea run", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.getIdeaRun", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "summary": "Delete the Cursor agent and local record for an idea run", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.deleteIdeaRun", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}/cancel": { "post": { "summary": "Cancel an active Cursor PR idea run", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.cancelIdeaRun", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}/archive": { "post": { "summary": "Archive the Cursor agent behind an idea run", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.archiveIdeaRun", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}/questions": { "post": { "summary": "Ask clarification questions for a selected Cursor PR idea", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.requestIdeaQuestions", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "selectedIdea": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "selectedIdea" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "202": { "description": "202", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}/answers": { "post": { "summary": "Submit clarification answers and request a build plan", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.submitIdeaAnswers", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } } }, "required": [ "answers" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "202": { "description": "202", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}/approve-plan": { "post": { "summary": "Approve the generated build plan and start implementation", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.approveIdeaPlan", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "202": { "description": "202", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}/open-pr": { "post": { "summary": "Open a pull request for a built Cursor idea run", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.openIdeaPr", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "202": { "description": "202", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/cursor/idea-runs/{runId}/recover-agent": { "post": { "summary": "Start a fresh Cursor Cloud Agent from the current workflow context", "tags": [ "cursor" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "cursor.recoverIdeaAgent", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "202": { "description": "202", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "running", "finished", "error", "cancelled" ] }, "workflowStage": { "type": "string", "enum": [ "ideas", "questions", "planning", "plan_approval", "building", "ready_for_pr", "pr_open", "pr_commented_on", "pr_merged" ] }, "cursorAgentId": { "type": "string" }, "cursorRunId": { "type": "string" }, "cursorAgentUrl": { "type": "string", "format": "uri" }, "questionRunId": { "type": "string" }, "planRunId": { "type": "string" }, "buildRunId": { "type": "string" }, "prRunId": { "type": "string" }, "prompt": { "type": "string" }, "inputs": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "idea", "issue" ] }, "interests": { "type": "string", "maxLength": 500 }, "skills": { "type": "string", "maxLength": 500 }, "preferredArea": { "type": "string", "maxLength": 160 }, "constraints": { "type": "string", "maxLength": 500 }, "freeform": { "type": "string", "maxLength": 2000 }, "issueNumber": { "type": "string", "maxLength": 20 }, "issueTitle": { "type": "string", "maxLength": 500 }, "issueBody": { "type": "string", "maxLength": 4000 }, "issueUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "issueLabels": { "type": "string", "maxLength": 500 } } }, "result": { "type": "string", "nullable": true }, "selectedIdea": { "type": "string", "nullable": true }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string" } }, "required": [ "id", "question" ] } }, "answersSubmittedAt": { "type": "string", "nullable": true }, "buildPlan": { "type": "string", "nullable": true }, "buildResult": { "type": "string", "nullable": true }, "planApprovedAt": { "type": "string", "nullable": true }, "pr": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "opening", "pr_open", "pr_commented_on", "pr_merged" ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "number": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0, "nullable": true }, "openedAt": { "type": "string", "nullable": true }, "lastCommentedAt": { "type": "string", "nullable": true }, "mergedAt": { "type": "string", "nullable": true } }, "required": [ "status" ], "nullable": true }, "git": { "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string" } }, "required": [ "path", "sizeBytes", "updatedAt" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "thinking", "status", "tool", "shell" ] } }, "required": [ "id", "role", "summary" ] } }, "cursorStatusDetail": { "type": "string", "nullable": true }, "cursorLastActivityAt": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "prompt", "inputs" ] } }, "required": [ "ok", "run" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/discord/authorize": { "get": { "summary": "Begin Discord OAuth — redirects to discord.com", "tags": [ "discord" ], "parameters": [ { "name": "returnTo", "in": "query", "schema": { "type": "string" } } ], "operationId": "discord.authorize", "responses": { "302": { "description": "302", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/discord/callback": { "get": { "summary": "Discord OAuth callback — finishes the link and redirects", "tags": [ "discord" ], "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "operationId": "discord.callback", "responses": { "302": { "description": "302", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/events/{eventId}/coworking/eligibility": { "get": { "description": "Returns 200 with `eligible:false` when unauthenticated rather than 401, so the page can render a 'sign in' affordance.", "summary": "Check coworking eligibility for the current user", "tags": [ "events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "events.coworkingEligibility", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "eligible" ], "additionalProperties": true } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/events/{eventId}/coworking/register": { "post": { "summary": "Register for a coworking session in an event", "tags": [ "events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "events.coworkingRegister", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "sessionId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "registration": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "message" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "summary": "Cancel the current user's coworking registration", "tags": [ "events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "events.coworkingCancel", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/events/{eventId}/coworking/slots": { "get": { "description": "Authentication optional; if present, includes user-specific status.", "summary": "List coworking sessions with availability for an event", "tags": [ "events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "events.coworkingSlots", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "eventId": { "type": "string" }, "sessions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "success", "eventId", "sessions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/events/pydata-2026/admin/list": { "get": { "summary": "Admin: paginated PyData 2026 registrations with cap-vs-waitlist", "tags": [ "events" ], "parameters": [], "operationId": "events.pydataAdminList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "capacity": { "type": "integer", "minimum": 0 }, "inCapCount": { "type": "integer", "minimum": 0 }, "waitlistCount": { "type": "integer", "minimum": 0 }, "registrations": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "total", "counts", "capacity", "inCapCount", "waitlistCount", "registrations" ], "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/events/pydata-2026/capacity": { "get": { "summary": "Public PyData 2026 capacity / claimed / remaining counts", "tags": [ "events" ], "parameters": [], "operationId": "events.pydataCapacity", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "capacity": { "type": "integer", "minimum": 0 }, "claimed": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "full": { "type": "boolean" } }, "required": [ "capacity", "claimed", "remaining", "full" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/events/pydata-2026/luma-status": { "get": { "summary": "Whether the current user appears on the PyData Luma guest list", "tags": [ "events" ], "parameters": [], "operationId": "events.pydataLumaStatus", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "signedIn": { "type": "boolean" }, "onLumaList": { "type": "boolean" } }, "required": [ "signedIn", "onLumaList" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/events/pydata-2026/access": { "get": { "summary": "Whether the signed-in user is on the 150-person PyData 2026 door list", "tags": [ "events" ], "parameters": [], "operationId": "events.pydataAccess", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "allowed" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/events/pydata-2026/registration": { "get": { "summary": "Get the current user's PyData 2026 registration (if any)", "tags": [ "events" ], "parameters": [], "operationId": "events.pydataRegistrationGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "registered": { "type": "boolean" }, "registration": { "type": "object", "properties": {}, "additionalProperties": true, "nullable": true } }, "required": [ "registered", "registration" ], "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Create or update the current user's PyData 2026 registration", "tags": [ "events" ], "parameters": [], "operationId": "events.pydataRegistrationPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "phone": { "default": "", "type": "string" }, "organization": { "type": "string", "minLength": 1 }, "attendingConfirmed": { "type": "boolean", "enum": [ true ] } }, "required": [ "firstName", "lastName", "email", "organization", "attendingConfirmed" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "isFirstSubmission": { "type": "boolean" } }, "required": [ "ok", "isFirstSubmission" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/events/pydata-2026/withdraw": { "post": { "summary": "Two-step PyData withdrawal: confirmation page POSTs here with HMAC token", "tags": [ "events" ], "parameters": [], "operationId": "events.pydataWithdraw", "requestBody": { "description": "Body", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "email", "token" ] } } } }, "responses": { "303": { "description": "303", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } } }, "/api/game/leaderboard": { "get": { "description": "Returns players ranked by `stats.tilesHeld` descending. Cursor-paginated; default page size is 20 (max 100). `audience` filters to `npc`, `real`, or `all` (default).", "summary": "Get the leaderboard ranked by tiles held", "tags": [ "game" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "audience", "in": "query", "schema": { "type": "string", "enum": [ "all", "npc", "real" ] } } ], "operationId": "game.getLeaderboard", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "players": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string" }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "userId", "displayName", "caste", "phase", "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ] } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "success", "players", "nextCursor", "hasMore" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/attacks": { "get": { "description": "Cursor-paginated when `side=sent` or `side=received`. `side=all` merges the two views in memory and is bounded at 500 per side.", "summary": "List the player's attacks (sent/received/all)", "tags": [ "game" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "side", "in": "query", "schema": { "type": "string", "enum": [ "sent", "received", "all" ] } } ], "operationId": "game.getAttacks", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "attacks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "attackerId": { "type": "string" }, "defenderId": { "type": "string" }, "targetTileId": { "type": "string" }, "sourceTileIds": { "type": "array", "items": { "type": "string" } }, "unitsSent": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "unitsLostAttacker": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "unitsLostDefender": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "outcome": { "type": "string" }, "turnsCost": { "type": "integer", "minimum": 0 }, "casteAttacker": { "type": "string", "enum": [ "military", "food", "magic" ] }, "casteDefender": { "type": "string", "enum": [ "military", "food", "magic" ] }, "offenseSpellId": { "type": "string", "nullable": true }, "defenseSpellId": { "type": "string", "nullable": true } }, "required": [ "attackerId", "defenderId", "targetTileId", "sourceTileIds", "unitsSent", "unitsLostAttacker", "unitsLostDefender", "outcome", "turnsCost", "casteAttacker", "casteDefender", "offenseSpellId", "defenseSpellId" ], "additionalProperties": true } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "success", "attacks", "nextCursor", "hasMore" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/artifacts": { "get": { "summary": "List the player's artifact inventory", "tags": [ "game" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } } ], "operationId": "game.getArtifacts", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ownerId": { "type": "string" }, "definitionId": { "type": "string" }, "rarity": { "type": "string", "enum": [ "common", "rare", "epic", "legendary" ] }, "type": { "type": "string", "enum": [ "offense", "defense", "production", "utility" ] }, "foundAtTurn": { "type": "integer" }, "used": { "type": "boolean" } }, "required": [ "id", "ownerId", "definitionId", "rarity", "type", "foundAtTurn", "used" ], "additionalProperties": true } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "success", "artifacts", "nextCursor", "hasMore" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/player": { "get": { "summary": "Get the current user's game profile + visible tiles", "tags": [ "game" ], "parameters": [], "operationId": "game.getPlayer", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true, "nullable": true }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "isAdmin": { "type": "boolean" } }, "required": [ "success", "player", "tiles", "isAdmin" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Create the current user's game profile", "tags": [ "game" ], "parameters": [], "operationId": "game.createPlayer", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1 } }, "required": [ "displayName" ] } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tileIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "player", "tileIds" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "summary": "Rename the current user's general (display name)", "tags": [ "game" ], "parameters": [], "operationId": "game.renamePlayer", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1 } }, "required": [ "displayName" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/world-3d": { "get": { "description": "Returns the once-per-day denormalized world snapshot used by /game/world. No auth required. Responds with `{ tiles: [], generatedAt: null, tileCount: 0 }` until the first cron writes the underlying doc.", "summary": "Public 3D flyover world snapshot (daily, anonymous-accessible)", "tags": [ "game" ], "parameters": [], "operationId": "game.getWorld3d", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiles": { "type": "array", "items": { "type": "object", "properties": { "tileId": { "type": "string" }, "q": { "type": "number" }, "r": { "type": "number" }, "type": { "type": "string", "enum": [ "unrevealed", "unassigned", "military", "food", "magic" ] }, "ownerId": { "type": "string", "nullable": true }, "ownerName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ], "nullable": true }, "isNpc": { "type": "boolean" }, "level": { "type": "number" }, "hasExtraForces": { "type": "boolean" }, "hasHero": { "type": "boolean" }, "ownerShielded": { "type": "boolean" } }, "required": [ "tileId", "q", "r", "type", "ownerId", "ownerName", "caste", "isNpc", "level", "hasExtraForces", "hasHero", "ownerShielded" ] } }, "generatedAt": { "type": "string", "nullable": true }, "tileCount": { "type": "number" } }, "required": [ "tiles", "generatedAt", "tileCount" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/game/world": { "get": { "description": "When `qMin`/`qMax`/`rMin`/`rMax` are all provided, returns tiles within that axial bounding box. Otherwise returns the full visible world (legacy mode).", "summary": "Fetch tiles for the world map (full or bbox)", "tags": [ "game" ], "parameters": [ { "name": "qMin", "in": "query", "schema": { "type": "string", "pattern": "^-?\\d+$" } }, { "name": "qMax", "in": "query", "schema": { "type": "string", "pattern": "^-?\\d+$" } }, { "name": "rMin", "in": "query", "schema": { "type": "string", "pattern": "^-?\\d+$" } }, { "name": "rMax", "in": "query", "schema": { "type": "string", "pattern": "^-?\\d+$" } } ], "operationId": "game.getWorld", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "owners": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Legacy mode only — present when the request omits a bbox" } }, "required": [ "success", "tiles" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/map/me": { "get": { "description": "Returns the user's owned tiles plus the enemy-owned border ring touching them, with owner summaries for those enemies. Read cost scales with kingdom perimeter rather than world size.", "summary": "Get the current user's personal map view (own tiles + enemy ring)", "tags": [ "game" ], "parameters": [], "operationId": "game.getMyMap", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "myTiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "borderTiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "owners": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "success", "myTiles", "borderTiles", "owners" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/tile/{tileId}": { "get": { "summary": "Get a single tile by id", "tags": [ "game" ], "parameters": [ { "name": "tileId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "game.getTile", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "required": [ "success", "tile" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/eligibility": { "get": { "summary": "Get the current user's game eligibility state", "tags": [ "game" ], "parameters": [], "operationId": "game.getEligibility", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ], "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/setup/caste": { "post": { "summary": "Choose initial caste during onboarding", "tags": [ "game" ], "parameters": [], "operationId": "game.setupCaste", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ] } }, "required": [ "caste" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/caste/change": { "post": { "description": "Allows a single permanent caste change once `stats.tilesHeld >= 1000`. The first caste pick is treated as experimental; this endpoint flips the player to a new caste and increments `casteChangesUsed` to 1. Subsequent attempts return CONFLICT.", "summary": "Switch castes (one-time, after reaching 1000 tiles)", "tags": [ "game" ], "parameters": [], "operationId": "game.changeCaste", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ] } }, "required": [ "caste" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/setup/distribute": { "post": { "summary": "Distribute land type to a tile during onboarding", "tags": [ "game" ], "parameters": [], "operationId": "game.setupDistribute", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "tileId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": [ "tileId", "type", "count" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/setup/explore": { "post": { "summary": "Frontier-explore tiles during onboarding", "tags": [ "game" ], "parameters": [], "operationId": "game.setupExplore", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" } }, "required": [ "success", "player" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/explore": { "post": { "summary": "Frontier-explore one or more new tiles", "tags": [ "game" ], "parameters": [], "operationId": "game.explore", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" }, "frontier": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/explore/far": { "post": { "summary": "Spend 2 turns to plant a tile adjacent to a random enemy tile (Far Expedition).", "tags": [ "game" ], "parameters": [], "operationId": "game.farExpedition", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" }, "targetEnemyTileId": { "type": "string" }, "enemyTile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true, "nullable": true } }, "required": [ "success", "player", "targetEnemyTileId", "enemyTile" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/spy": { "post": { "summary": "Cast an intel ('spy') spell on an enemy tile.", "tags": [ "game" ], "parameters": [], "operationId": "game.spy", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "spellId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string", "minLength": 1 } }, "required": [ "spellId", "targetTileId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" }, "intelReport": { "type": "object", "properties": {}, "additionalProperties": true }, "detected": { "type": "boolean" } }, "required": [ "success", "player", "intelReport", "detected" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/explore/bulk": { "post": { "summary": "Bulk frontier-explore (count required)", "tags": [ "game" ], "parameters": [], "operationId": "game.exploreBulk", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": [ "count" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" }, "frontiers": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "success", "player", "tiles", "reports", "frontiers" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/build": { "post": { "summary": "Build units on a tile", "tags": [ "game" ], "parameters": [], "operationId": "game.build", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "tileId": { "type": "string", "minLength": 1 }, "unitType": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": [ "tileId", "unitType" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" }, "produced": { "type": "integer", "minimum": 0 } }, "required": [ "success", "player", "produced" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/build/bulk": { "post": { "summary": "Execute a bulk build plan across tiles", "tags": [ "game" ], "parameters": [], "operationId": "game.buildBulk", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "array", "items": { "type": "object", "properties": { "tileId": { "type": "string", "minLength": 1 }, "unitType": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "cycles": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": [ "tileId", "unitType", "cycles" ] }, "minItems": 1 } }, "required": [ "plan" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" }, "produced": { "type": "integer", "minimum": 0 } }, "required": [ "success", "player", "tiles", "reports", "produced" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/distribute/bulk": { "post": { "summary": "Distribute one land type across multiple tiles", "tags": [ "game" ], "parameters": [], "operationId": "game.distributeBulk", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "tileIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] } }, "required": [ "tileIds", "type" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" } }, "required": [ "success", "player", "tiles", "reports" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/attack": { "post": { "summary": "Launch an attack from one of your tiles", "tags": [ "game" ], "parameters": [], "operationId": "game.attack", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceTileId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string", "minLength": 1 }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "offenseSpellId": { "type": "string", "nullable": true }, "heroAction": { "type": "string", "enum": [ "kill", "spare", "convert" ] }, "heroActionOnConvertFail": { "type": "string", "enum": [ "kill", "spare" ] }, "dispatch": { "type": "string", "maxLength": 280 } }, "required": [ "sourceTileId", "targetTileId", "units" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "attack": { "type": "object", "properties": { "id": { "type": "string" }, "attackerId": { "type": "string" }, "defenderId": { "type": "string" }, "targetTileId": { "type": "string" }, "sourceTileIds": { "type": "array", "items": { "type": "string" } }, "unitsSent": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "unitsLostAttacker": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "unitsLostDefender": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "outcome": { "type": "string" }, "turnsCost": { "type": "integer", "minimum": 0 }, "casteAttacker": { "type": "string", "enum": [ "military", "food", "magic" ] }, "casteDefender": { "type": "string", "enum": [ "military", "food", "magic" ] }, "offenseSpellId": { "type": "string", "nullable": true }, "defenseSpellId": { "type": "string", "nullable": true } }, "required": [ "attackerId", "defenderId", "targetTileId", "sourceTileIds", "unitsSent", "unitsLostAttacker", "unitsLostDefender", "outcome", "turnsCost", "casteAttacker", "casteDefender", "offenseSpellId", "defenseSpellId" ], "additionalProperties": true }, "attackerPlayer": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "sourceTile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "targetTile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "combat": { "type": "object", "properties": { "outcome": { "type": "string" }, "unitsDeployed": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "unitsClampedFromCapacity": { "type": "integer", "minimum": 0 }, "attackPower": { "type": "number" }, "defensePower": { "type": "number" }, "attackerLosses": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "defenderLosses": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "underdogApplied": { "type": "boolean" }, "supplyMultiplier": { "type": "number" }, "rng": { "type": "object", "properties": { "attackerRoll": { "type": "number" }, "defenderRoll": { "type": "number" } }, "required": [ "attackerRoll", "defenderRoll" ] }, "appliedSpells": { "type": "object", "properties": { "offenseId": { "type": "string", "nullable": true }, "defenseId": { "type": "string", "nullable": true } }, "required": [ "offenseId", "defenseId" ] }, "airIntel": { "type": "object", "properties": { "sourcePassive": { "type": "string" }, "defenseSpellTier": { "type": "integer" }, "weakFace": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "forgeScoutsBonusApplied": { "type": "boolean" } }, "required": [ "sourcePassive" ], "additionalProperties": true } }, "required": [ "outcome", "unitsDeployed", "unitsClampedFromCapacity", "attackPower", "defensePower", "attackerLosses", "defenderLosses", "underdogApplied", "supplyMultiplier", "rng", "appliedSpells" ], "additionalProperties": true }, "intelReport": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "attack", "attackerPlayer", "sourceTile", "targetTile", "report" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/attack/preview": { "post": { "description": "Runs the same combat math as `/api/game/attack` but with a fixed midpoint RNG seed and no writes / turn deduction. The resulting CombatResult is the 'expected' outcome a player would see if they swung now with the supplied stack. Active prep effects (siege, pre-cast, disarm, forge-sight, alert) are also reflected.", "summary": "Project the outcome of a hypothetical attack", "tags": [ "game" ], "parameters": [], "operationId": "game.attackPreview", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceTileId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string", "minLength": 1 }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "offenseSpellId": { "type": "string", "nullable": true }, "heroAction": { "type": "string", "enum": [ "kill", "spare", "convert" ] }, "heroActionOnConvertFail": { "type": "string", "enum": [ "kill", "spare" ] }, "dispatch": { "type": "string", "maxLength": 280 } }, "required": [ "sourceTileId", "targetTileId", "units" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "combat": { "type": "object", "properties": { "outcome": { "type": "string" }, "unitsDeployed": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "unitsClampedFromCapacity": { "type": "integer", "minimum": 0 }, "attackPower": { "type": "number" }, "defensePower": { "type": "number" }, "attackerLosses": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "defenderLosses": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "underdogApplied": { "type": "boolean" }, "supplyMultiplier": { "type": "number" }, "rng": { "type": "object", "properties": { "attackerRoll": { "type": "number" }, "defenderRoll": { "type": "number" } }, "required": [ "attackerRoll", "defenderRoll" ] }, "appliedSpells": { "type": "object", "properties": { "offenseId": { "type": "string", "nullable": true }, "defenseId": { "type": "string", "nullable": true } }, "required": [ "offenseId", "defenseId" ] }, "airIntel": { "type": "object", "properties": { "sourcePassive": { "type": "string" }, "defenseSpellTier": { "type": "integer" }, "weakFace": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "forgeScoutsBonusApplied": { "type": "boolean" } }, "required": [ "sourcePassive" ], "additionalProperties": true } }, "required": [ "outcome", "unitsDeployed", "unitsClampedFromCapacity", "attackPower", "defensePower", "attackerLosses", "defenderLosses", "underdogApplied", "supplyMultiplier", "rng", "appliedSpells" ], "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "target": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "defender": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string" }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "shielded": { "type": "boolean" } }, "required": [ "userId", "displayName", "caste", "shielded" ] }, "effects": { "type": "object", "properties": { "forgeSightOffenseBonus": { "type": "number" }, "alertVsCasterDefenseBonus": { "type": "number" }, "siegeDebuffMagnitude": { "type": "number" }, "preCastOffenseBonus": { "type": "number" }, "defenseDisarmFraction": { "type": "number" } }, "required": [ "forgeSightOffenseBonus", "alertVsCasterDefenseBonus", "siegeDebuffMagnitude", "preCastOffenseBonus", "defenseDisarmFraction" ] } }, "required": [ "success", "combat", "source", "target", "defender", "effects" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/siege": { "post": { "description": "Costs 5 turns. Records a `siege-debuff` IntelEffect on the target with magnitude `SIEGE_ACTION_MAGNITUDE` (0.10) and a 5-attacker-turn TTL. Stacks across calls until SIEGE_DEBUFF_MAX_MAGNITUDE (0.30). Source must be owned and adjacent to target.", "summary": "Soften a target tile's standing-defense floor", "tags": [ "game" ], "parameters": [], "operationId": "game.siege", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceTileId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string", "minLength": 1 } }, "required": [ "sourceTileId", "targetTileId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "siegeTotalMagnitude": { "type": "number" } }, "required": [ "success", "player", "report", "siegeTotalMagnitude" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/flyover": { "post": { "description": "Air-only attack with the capture branch disabled. Always resolves to 'repelled' or 'stalemate'; tile ownership never changes. Attacker losses are doubled (`2× resolveAttack` losses, clamped to deployed) — a deliberate suicide-mission trade. Costs `ATTACK_TURN_COST` (1 turn).", "summary": "Air raid that attrits defenders without taking the tile", "tags": [ "game" ], "parameters": [], "operationId": "game.flyover", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceTileId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string", "minLength": 1 }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "sourceTileId", "targetTileId", "units" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "attackerPlayer": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "sourceTile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "targetTile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "combat": { "type": "object", "properties": { "outcome": { "type": "string" }, "unitsDeployed": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "unitsClampedFromCapacity": { "type": "integer", "minimum": 0 }, "attackPower": { "type": "number" }, "defensePower": { "type": "number" }, "attackerLosses": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "defenderLosses": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "underdogApplied": { "type": "boolean" }, "supplyMultiplier": { "type": "number" }, "rng": { "type": "object", "properties": { "attackerRoll": { "type": "number" }, "defenderRoll": { "type": "number" } }, "required": [ "attackerRoll", "defenderRoll" ] }, "appliedSpells": { "type": "object", "properties": { "offenseId": { "type": "string", "nullable": true }, "defenseId": { "type": "string", "nullable": true } }, "required": [ "offenseId", "defenseId" ] }, "airIntel": { "type": "object", "properties": { "sourcePassive": { "type": "string" }, "defenseSpellTier": { "type": "integer" }, "weakFace": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "forgeScoutsBonusApplied": { "type": "boolean" } }, "required": [ "sourcePassive" ], "additionalProperties": true } }, "required": [ "outcome", "unitsDeployed", "unitsClampedFromCapacity", "attackPower", "defensePower", "attackerLosses", "defenderLosses", "underdogApplied", "supplyMultiplier", "rng", "appliedSpells" ], "additionalProperties": true } }, "required": [ "success", "attackerPlayer", "sourceTile", "targetTile", "report", "combat" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/spell/cast": { "post": { "description": "Dispatches on the spell's `type`. Each kind rolls dice once (SPELL_RNG band 0.5–1.5) and either persists an IntelEffect (siege, disarm) or commits unit losses immediately (attrition). Validates ownership + adjacency + non-shield + caste-match + tier tile-min + turn budget.", "summary": "Cast a standalone siege/disarm/attrition spell against a target tile", "tags": [ "game" ], "parameters": [], "operationId": "game.castSpell", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "spellId": { "type": "string", "minLength": 1 }, "sourceTileId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string", "minLength": 1 } }, "required": [ "spellId", "sourceTileId", "targetTileId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "siege": { "type": "object", "properties": { "magnitudeApplied": { "type": "number" }, "totalMagnitudeAfter": { "type": "number" } }, "required": [ "magnitudeApplied", "totalMagnitudeAfter" ] }, "disarm": { "type": "object", "properties": { "fractionApplied": { "type": "number" } }, "required": [ "fractionApplied" ] }, "attrition": { "type": "object", "properties": { "unitsKilled": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] }, "targetTile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "required": [ "unitsKilled", "targetTile" ] } }, "required": [ "success", "player", "report" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/artifact/use": { "post": { "summary": "Spend an artifact (optionally on a target tile)", "tags": [ "game" ], "parameters": [], "operationId": "game.artifactUse", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifactId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string" } }, "required": [ "artifactId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "ownerId": { "type": "string" }, "definitionId": { "type": "string" }, "rarity": { "type": "string", "enum": [ "common", "rare", "epic", "legendary" ] }, "type": { "type": "string", "enum": [ "offense", "defense", "production", "utility" ] }, "foundAtTurn": { "type": "integer" }, "used": { "type": "boolean" } }, "required": [ "id", "ownerId", "definitionId", "rarity", "type", "foundAtTurn", "used" ], "additionalProperties": true }, "intelReport": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "artifact" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/spell/arm": { "post": { "description": "Pass `tileId` for single mode or `tileIds` for bulk mode. Bulk returns per-tile success/failure.", "summary": "Arm a defense spell on one tile (single) or many (bulk)", "tags": [ "game" ], "parameters": [], "operationId": "game.spellArm", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "spellId": { "type": "string", "minLength": 1 }, "tileId": { "type": "string" }, "tileIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": [ "spellId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" } }, "required": [ "success", "player" ] }, { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true, "nullable": true }, "armed": { "type": "integer", "minimum": 0 }, "failed": { "type": "array", "items": { "type": "object", "properties": { "tileId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "tileId", "reason" ] } }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "success", "player", "armed", "failed", "reports" ] } ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/spell/produce": { "post": { "summary": "Cast a production spell (with optional batch count)", "tags": [ "game" ], "parameters": [], "operationId": "game.spellProduce", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "spellId": { "type": "string", "minLength": 1 }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": [ "spellId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true }, "report": { "type": "object", "properties": {}, "additionalProperties": true }, "reports": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "stoppedEarly": { "type": "boolean" } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/upgrades/apply": { "post": { "summary": "Apply an upgrade to a target", "tags": [ "game" ], "parameters": [], "operationId": "game.upgradesApply", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetId": { "type": "string", "minLength": 1 }, "upgradeId": { "type": "string", "minLength": 1 } }, "required": [ "targetId", "upgradeId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/upgrades/remove": { "post": { "summary": "Remove an upgrade from a target", "tags": [ "game" ], "parameters": [], "operationId": "game.upgradesRemove", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetId": { "type": "string", "minLength": 1 } }, "required": [ "targetId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/special-units/summon": { "post": { "summary": "Station a caste-themed special unit on one of your tiles", "tags": [ "game" ], "parameters": [], "operationId": "game.specialUnitsSummon", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1 }, "targetTileId": { "type": "string", "minLength": 1 } }, "required": [ "instanceId", "targetTileId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tileId": { "type": "string" } }, "required": [ "success", "player", "tileId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/special-units/unsummon": { "post": { "summary": "Recall a stationed special unit back into your pool", "tags": [ "game" ], "parameters": [], "operationId": "game.specialUnitsUnsummon", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1 } }, "required": [ "instanceId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/rollover": { "post": { "description": "Authenticated by an `x-rollover-secret` header rather than Firebase Auth. Idempotent for a given `weekStartIso`.", "summary": "Cron-only weekly turn-grant rollover", "tags": [ "game" ], "parameters": [ { "name": "weekStartIso", "in": "query", "schema": { "type": "string" } } ], "operationId": "game.rollover", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "summary": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "summary" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/game/npc-weekly": { "post": { "description": "Authenticated by the same `x-rollover-secret` header used by the human rollover. Iterates every NPC, applies the weekly grant, and spends ~all 100 turns per persona-driven action plan. Idempotent for a given `weekStartIso`.", "summary": "Cron-only weekly NPC turn-spender", "tags": [ "game" ], "parameters": [ { "name": "weekStartIso", "in": "query", "schema": { "type": "string" } }, { "name": "dryRun", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "operationId": "game.npcWeekly", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "summary": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "summary" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/game/admin/grant": { "post": { "summary": "Admin: grant turns to a user (testing helper)", "tags": [ "game" ], "parameters": [], "operationId": "game.adminGrant", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "weekStartIso": { "type": "string" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true } }, "required": [ "success", "player" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/admin/units": { "post": { "summary": "Admin: drop units on a tile (bootstrap helper)", "tags": [ "game" ], "parameters": [], "operationId": "game.adminUnits", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string" }, "tileId": { "type": "string" }, "unitType": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "player": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "caste": { "type": "string", "enum": [ "military", "food", "magic" ], "nullable": true }, "phase": { "type": "string", "enum": [ "onboarding", "active", "eliminated" ] }, "stats": { "type": "object", "properties": { "tilesHeld": { "type": "integer", "minimum": 0 }, "unitsAlive": { "type": "integer", "minimum": 0 }, "attacksWon": { "type": "integer", "minimum": 0 }, "attacksLost": { "type": "integer", "minimum": 0 } }, "required": [ "tilesHeld", "unitsAlive", "attacksWon", "attacksLost" ], "additionalProperties": true } }, "required": [ "userId" ], "additionalProperties": true }, "tile": { "type": "object", "properties": { "id": { "type": "string" }, "q": { "type": "integer" }, "r": { "type": "integer" }, "type": { "type": "string", "enum": [ "military", "food", "magic", "unassigned" ] }, "ownerId": { "type": "string", "nullable": true }, "units": { "type": "object", "properties": { "ground": { "type": "integer", "minimum": 0 }, "siege": { "type": "integer", "minimum": 0 }, "air": { "type": "integer", "minimum": 0 } }, "required": [ "ground", "siege", "air" ] } }, "required": [ "q", "r" ], "additionalProperties": true } }, "required": [ "success", "player", "tile" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/community/feed": { "get": { "description": "Returns the most recent 50 community-events ordered by createdAt desc. CDN-cached for ~30s.", "summary": "Recent community events (player joins, caste picks, attacks)", "tags": [ "game" ], "parameters": [], "operationId": "game.getCommunityFeed", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "player_join", "caste_pick", "caste_change", "attack", "milestone_1k_tiles" ] }, "actorUserId": { "type": "string" }, "actorDisplayName": { "type": "string" }, "actorCaste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ], "nullable": true }, "targetUserId": { "type": "string" }, "targetDisplayName": { "type": "string" }, "tileId": { "type": "string" }, "outcome": { "type": "string", "enum": [ "captured", "repelled", "stalemate" ] }, "fromCaste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ] }, "toCaste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ] } }, "required": [ "id", "kind", "actorUserId", "actorDisplayName", "actorCaste" ], "additionalProperties": true } } }, "required": [ "success", "events" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/community/chat": { "get": { "description": "Returns the most recent 50 non-deleted chat messages ordered by createdAt desc.", "summary": "Recent community chat messages", "tags": [ "game" ], "parameters": [], "operationId": "game.getCommunityChat", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ], "nullable": true }, "body": { "type": "string" }, "deletedByAdmin": { "type": "boolean" } }, "required": [ "id", "userId", "displayName", "caste", "body" ], "additionalProperties": true } } }, "required": [ "success", "messages" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Post a chat message (rate-limited: 10 / 60s per user)", "tags": [ "game" ], "parameters": [], "operationId": "game.postCommunityChat", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ], "nullable": true }, "body": { "type": "string" }, "deletedByAdmin": { "type": "boolean" } }, "required": [ "id", "userId", "displayName", "caste", "body" ], "additionalProperties": true } }, "required": [ "success", "message" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/community/chat/{messageId}": { "delete": { "description": "Soft-delete: sets deletedAt + deletedByAdmin. Author can delete their own; admins can delete any.", "summary": "Delete a chat message (own or admin)", "tags": [ "game" ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "game.deleteCommunityChat", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ], "nullable": true }, "body": { "type": "string" }, "deletedByAdmin": { "type": "boolean" } }, "required": [ "id", "userId", "displayName", "caste", "body" ], "additionalProperties": true } }, "required": [ "success", "message" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/heroes": { "get": { "description": "`scope=mine` returns heroes the viewer currently owns. `scope=all` (default) returns every living hero with location hidden unless visible. `scope=fallen` returns deceased + past-season heroes, fully public.", "summary": "List heroes (mine / all living / fallen)", "tags": [ "game" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "mine", "all", "fallen" ] } } ], "operationId": "game.getHeroesList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "heroes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "class": { "type": "string", "enum": [ "military", "farm", "magic" ] }, "specialty": { "type": "string", "enum": [ "ground", "siege", "air", "garrison", "raid", "supply", "ground-recruit", "siege-recruit", "air-recruit", "summoner", "kingdom-buff", "spellcasting", "armageddon", "offense-spells", "defense-spells", "spying", "production-spells" ] }, "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ] }, "currentOwnerId": { "type": "string", "nullable": true }, "isDeceased": { "type": "boolean" }, "awaitingResurrection": { "type": "boolean" }, "emergedSeasonNumber": { "type": "integer", "minimum": 0 }, "hasBackstory": { "type": "boolean" }, "currentTileId": { "type": "string" }, "deceasedTileId": { "type": "string" }, "stamina": { "type": "integer", "minimum": 0 }, "staminaMax": { "type": "integer", "minimum": 0 } }, "required": [ "id", "name", "class", "specialty", "caste", "currentOwnerId", "isDeceased", "awaitingResurrection", "emergedSeasonNumber", "hasBackstory" ] } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "success", "heroes", "nextCursor", "hasMore" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/heroes/{heroId}": { "get": { "description": "Visibility filter applied to both the hero summary (location / stamina) and the events list (tenure-scoped for living heroes; fully public for deceased / past-season heroes).", "summary": "Get a hero's profile + first page of events", "tags": [ "game" ], "parameters": [ { "name": "heroId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "game.getHeroDetail", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "hero": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "class": { "type": "string", "enum": [ "military", "farm", "magic" ] }, "specialty": { "type": "string", "enum": [ "ground", "siege", "air", "garrison", "raid", "supply", "ground-recruit", "siege-recruit", "air-recruit", "summoner", "kingdom-buff", "spellcasting", "armageddon", "offense-spells", "defense-spells", "spying", "production-spells" ] }, "caste": { "type": "string", "enum": [ "black", "red", "white", "green", "blue" ] }, "currentOwnerId": { "type": "string", "nullable": true }, "isDeceased": { "type": "boolean" }, "awaitingResurrection": { "type": "boolean" }, "emergedSeasonNumber": { "type": "integer", "minimum": 0 }, "hasBackstory": { "type": "boolean" }, "currentTileId": { "type": "string" }, "deceasedTileId": { "type": "string" }, "stamina": { "type": "integer", "minimum": 0 }, "staminaMax": { "type": "integer", "minimum": 0 } }, "required": [ "id", "name", "class", "specialty", "caste", "currentOwnerId", "isDeceased", "awaitingResurrection", "emergedSeasonNumber", "hasBackstory" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "emerged", "engaged_attacker", "engaged_defender", "slain", "defected", "moved_on_capture", "spell_cast", "recruited", "special_unit_summoned", "season_ended" ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp" }, "tileId": { "type": "string" }, "ownerIdAtTime": { "type": "string", "nullable": true }, "seasonNumber": { "type": "integer", "minimum": 0 }, "attackerId": { "type": "string" }, "defenderId": { "type": "string" }, "outcome": { "type": "string", "enum": [ "captured", "repelled", "stalemate" ] }, "fromOwnerId": { "type": "string" }, "toOwnerId": { "type": "string" }, "fromTileId": { "type": "string" }, "spellId": { "type": "string" }, "targetTileId": { "type": "string" }, "unitType": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "unitsBuilt": { "type": "integer", "minimum": 0 }, "specialUnitDefId": { "type": "string" } }, "required": [ "id", "kind", "createdAt", "tileId", "ownerIdAtTime", "seasonNumber" ] } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "success", "hero", "events", "nextCursor", "hasMore" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/heroes/{heroId}/events": { "get": { "description": "Cursor-paginated. Living-hero events are tenure-filtered to the viewer; deceased / past-season hero events are fully public.", "summary": "Paginated event log for a hero", "tags": [ "game" ], "parameters": [ { "name": "heroId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } } ], "operationId": "game.getHeroEvents", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "emerged", "engaged_attacker", "engaged_defender", "slain", "defected", "moved_on_capture", "spell_cast", "recruited", "special_unit_summoned", "season_ended" ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp" }, "tileId": { "type": "string" }, "ownerIdAtTime": { "type": "string", "nullable": true }, "seasonNumber": { "type": "integer", "minimum": 0 }, "attackerId": { "type": "string" }, "defenderId": { "type": "string" }, "outcome": { "type": "string", "enum": [ "captured", "repelled", "stalemate" ] }, "fromOwnerId": { "type": "string" }, "toOwnerId": { "type": "string" }, "fromTileId": { "type": "string" }, "spellId": { "type": "string" }, "targetTileId": { "type": "string" }, "unitType": { "type": "string", "enum": [ "ground", "siege", "air" ] }, "unitsBuilt": { "type": "integer", "minimum": 0 }, "specialUnitDefId": { "type": "string" } }, "required": [ "id", "kind", "createdAt", "tileId", "ownerIdAtTime", "seasonNumber" ] } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "success", "events", "nextCursor", "hasMore" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/game/heroes/{heroId}/backstory": { "get": { "description": "Returns the raw markdown content from `lib/game/content/hero-backstories/.md`, or `markdown: null` if no chapter has been contributed yet.", "summary": "Get the markdown backstory for a hero, if one exists", "tags": [ "game" ], "parameters": [ { "name": "heroId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "game.getHeroBackstory", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "heroId": { "type": "string" }, "markdown": { "type": "string", "nullable": true } }, "required": [ "success", "heroId", "markdown" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/github/authorize": { "get": { "summary": "Begin GitHub OAuth — redirects to github.com", "tags": [ "github" ], "parameters": [ { "name": "returnTo", "in": "query", "schema": { "type": "string" } } ], "operationId": "github.authorize", "responses": { "302": { "description": "302", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/github/callback": { "get": { "summary": "GitHub OAuth callback — finishes the link and redirects", "tags": [ "github" ], "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "operationId": "github.callback", "responses": { "302": { "description": "302", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/github/webhook": { "get": { "summary": "Webhook health-check (GitHub fires GET on initial setup)", "tags": [ "github" ], "parameters": [], "operationId": "github.webhookPing", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } } } }, "post": { "description": "Body is verified via X-Hub-Signature-256 before any contract validation. The body shape mirrors the GitHub Webhooks API.", "summary": "GitHub webhook receiver (HMAC-signed by github.com)", "tags": [ "github" ], "parameters": [], "operationId": "github.webhook", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/eligibility": { "get": { "summary": "Get current user's hackathon eligibility", "tags": [ "hackathons" ], "parameters": [ { "name": "hackathonId", "in": "query", "schema": { "type": "string" } } ], "operationId": "hackathons.eligibility", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "eligible" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/events/{eventId}/signup": { "get": { "description": "30-second cached signup list with merged-PR counts.", "summary": "Public event-signup leaderboard", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventSignupGet", "responses": { "200": { "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type." } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Sign up the current user for an event", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventSignupPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "signedUp": { "type": "boolean" }, "alreadySignedUp": { "type": "boolean" } }, "required": [ "signedUp" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "summary": "Update the current user's signup state", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventSignupPatch", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "willBeLate": { "type": "boolean" }, "queuingForSpot": { "type": "boolean" }, "giveUpSpot": { "type": "boolean", "enum": [ true ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "summary": "Withdraw the current user's signup", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventSignupDelete", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/events/{eventId}/checkin": { "post": { "summary": "Admin-only: check a user in to an event", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventCheckin", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "checkedIn": { "type": "boolean" } }, "required": [ "userId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "checkedIn": { "type": "boolean" }, "created": { "type": "boolean" } }, "required": [ "ok", "checkedIn" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/events/{eventId}/confirm-attendance": { "post": { "description": "Idempotent second-step confirmation distinct from the rank-freeze 'confirmed seat' flow. Sets attendingConfirmedAt on the user's signup doc; preserved if already set. Returns the updated confirmed-attendee count and the per-event attendance limit.", "summary": "Confirm attendance for an event the user has signed up for", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventConfirmAttendancePost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "attendingConfirmed": { "type": "boolean" }, "attendingConfirmedAt": { "type": "string", "nullable": true }, "confirmedAttendeeCount": { "type": "number" }, "attendanceLimit": { "type": "number" } }, "required": [ "ok", "attendingConfirmed", "attendingConfirmedAt", "confirmedAttendeeCount", "attendanceLimit" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "description": "Idempotent. Clears attendingConfirmedAt while preserving the underlying signup. The user remains signed up but is no longer counted in the public confirmed-attendee count.", "summary": "Withdraw the user's attendance confirmation (keeps signup)", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventConfirmAttendanceDelete", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "attendingConfirmed": { "type": "boolean" }, "attendingConfirmedAt": { "type": "string", "nullable": true }, "confirmedAttendeeCount": { "type": "number" }, "attendanceLimit": { "type": "number" } }, "required": [ "ok", "attendingConfirmed", "attendingConfirmedAt", "confirmedAttendeeCount", "attendanceLimit" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/events/{eventId}/refresh-submissions": { "post": { "description": "Invalidates the 60s submission-author cache for three-tier events (sports-hack-2026) and rebuilds the leaderboard snapshot so a just-opened submission PR flips an attendee's hasSubmission / creditEligible flags immediately. Returns the post-refresh submission count and the snapshot generation timestamp. 404 for events that don't use the three-tier model.", "summary": "Admin-only — force-refresh the three-tier submission cache", "tags": [ "hackathons" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hackathons.eventRefreshSubmissions", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "eventId": { "type": "string" }, "submissionAuthorCount": { "type": "number" }, "generatedAt": { "type": "string" } }, "required": [ "ok", "eventId", "submissionAuthorCount", "generatedAt" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/invites/accept": { "post": { "summary": "Accept a team invite", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.inviteAccept", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "inviteId": { "type": "string", "minLength": 1 } }, "required": [ "inviteId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/pool-dashboard": { "get": { "summary": "Get the current user's hackathon pool dashboard", "tags": [ "hackathons" ], "parameters": [ { "name": "hackathonId", "in": "query", "schema": { "type": "string" } } ], "operationId": "hackathons.poolDashboard", "responses": { "200": { "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type." } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/pool/join": { "post": { "summary": "Join the hackathon pool (matchmaking)", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.poolJoin", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "hackathonId": { "type": "string" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "joined": { "type": "boolean" }, "hackathonId": { "type": "string" } }, "required": [ "joined", "hackathonId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/requests/accept": { "post": { "summary": "Accept a team-join request from another user", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.requestAccept", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/admin-dashboard": { "get": { "summary": "Admin: Hack-a-Sprint scoring dashboard", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintAdminDashboard", "responses": { "200": { "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type." } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/ai-score": { "post": { "summary": "Admin: set AI score (1-10) on a submission", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintAiScore", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionId": { "type": "string", "minLength": 1 }, "aiScore": { "type": "number", "minimum": 1, "maximum": 10 }, "aiReasoning": { "type": "string" } }, "required": [ "submissionId", "aiScore" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/credit-code": { "get": { "summary": "Get the current user's Cursor credit link", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintCreditCode", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "eligible": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string" } }, "required": [ "eligible" ] }, { "type": "object", "properties": { "eligible": { "type": "boolean", "enum": [ true ] }, "creditUrl": { "type": "string" }, "rank": { "type": "integer", "minimum": 0 } }, "required": [ "eligible", "creditUrl", "rank" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/credit-email": { "post": { "summary": "Email the credit link to the current user", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintCreditEmail", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "alreadySent": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "ok" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "emailedTo": { "type": "string" } }, "required": [ "ok", "emailedTo" ] } ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/judge-score": { "post": { "summary": "Judge: score a submission during peerVotingOpen", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintJudgeScore", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionId": { "type": "string", "minLength": 1 }, "score": { "type": "number", "minimum": 1, "maximum": 10 } }, "required": [ "submissionId", "score" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/me": { "get": { "summary": "Get the current user's Hack-a-Sprint state", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintMe", "responses": { "200": { "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type." } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/participant-score": { "post": { "summary": "Participant: score a peer submission", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintParticipantScore", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionId": { "type": "string", "minLength": 1 }, "score": { "type": "number", "minimum": 1, "maximum": 10 } }, "required": [ "submissionId", "score" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "submissionId": { "type": "string" }, "score": { "type": "number" } }, "required": [ "ok", "submissionId", "score" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/showcase/hack-a-sprint-2026/submissions": { "get": { "description": "Auth optional. Phase-aware — reveals scores and voter signal differently depending on submission/voting phase.", "summary": "Public Hack-a-Sprint submissions gallery", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintSubmissions", "responses": { "200": { "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type." } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/hackathons/showcase/hack-a-sprint-2026/unlock": { "post": { "description": "Always returns 410 Gone.", "summary": "Legacy passcode unlock (retired)", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintUnlock", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "410": { "description": "410", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/hackathons/showcase/hack-a-sprint-2026/vote": { "post": { "description": "Always returns 410 Gone.", "summary": "Legacy voting endpoint (retired — use participant-score)", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.hackASprintVote", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "410": { "description": "410", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/hackathons/submissions/check-disqualified": { "get": { "description": "Authenticated by `x-cron-secret` header (or `Authorization: Bearer`) rather than Firebase Auth.", "summary": "Cron: scan submissions for late commits and mark disqualified", "tags": [ "hackathons" ], "parameters": [ { "name": "hackathonId", "in": "query", "schema": { "type": "string" } } ], "operationId": "hackathons.submissionsCheckDisqualified", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "hackathonId": { "type": "string" }, "disqualifiedCount": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } }, "required": [ "hackathonId", "disqualifiedCount", "message" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/submissions/register": { "post": { "summary": "Register a team's repo URL for the hackathon", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.submissionRegister", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "hackathonId": { "type": "string" } }, "required": [ "repoUrl" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "registered": { "type": "boolean" }, "submissionId": { "type": "string" }, "repoUrl": { "type": "string" } }, "required": [ "registered", "submissionId", "repoUrl" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/submissions/submit": { "post": { "summary": "Lock the team's submission (sets submittedAt, cutoffAt)", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.submissionSubmit", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "hackathonId": { "type": "string" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "submitted": { "type": "boolean" }, "submissionId": { "type": "string" }, "cutoffAt": { "type": "string" } }, "required": [ "submitted", "submissionId", "cutoffAt" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/team-dashboard": { "get": { "summary": "Get the current user's team dashboard", "tags": [ "hackathons" ], "parameters": [ { "name": "hackathonId", "in": "query", "schema": { "type": "string" } } ], "operationId": "hackathons.teamDashboard", "responses": { "200": { "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type." } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/team/leave": { "post": { "summary": "Leave the user's current hackathon team", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.teamLeave", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string", "minLength": 1 } }, "required": [ "teamId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "left": { "type": "boolean" }, "disqualified": { "type": "boolean" }, "lockoutUntilNextMonth": { "type": "boolean" } }, "required": [ "left", "disqualified", "lockoutUntilNextMonth" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/team/profile": { "patch": { "summary": "Update the team's name / logo (gated on prior wins)", "tags": [ "hackathons" ], "parameters": [], "operationId": "hackathons.teamProfile", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "maxLength": 50 }, "logoUrl": { "type": "string" } }, "required": [ "teamId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hackathons/teams-board": { "get": { "description": "Authentication optional.", "summary": "Public hackathon teams board", "tags": [ "hackathons" ], "parameters": [ { "name": "hackathonId", "in": "query", "schema": { "type": "string" } } ], "operationId": "hackathons.teamsBoard", "responses": { "200": { "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Successful response — exact shape varies by helper. See the lib/hackathons module for the canonical type." } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/health": { "get": { "summary": "Liveness probe (always 200 if the app is up)", "tags": [ "health" ], "parameters": [], "operationId": "health.check", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy" ] }, "timestamp": { "type": "string" }, "version": { "type": "string" } }, "required": [ "status", "timestamp", "version" ] } } } } } } }, "/api/hiring-partners/apply": { "get": { "summary": "Get the current user's hiring-partner application", "tags": [ "hiringPartners" ], "parameters": [], "operationId": "hiringPartners.applyGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Create or update the current user's hiring-partner application", "tags": [ "hiringPartners" ], "parameters": [], "operationId": "hiringPartners.applyPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactName": { "nullable": true }, "phone": { "nullable": true }, "companyName": { "nullable": true }, "companyWebsite": { "nullable": true }, "contactRole": { "nullable": true }, "rolesHiring": { "nullable": true }, "notes": { "nullable": true }, "engineerExpectations": { "type": "object", "additionalProperties": {} }, "engineerRequirements": { "nullable": true } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/hunt/status": { "get": { "summary": "Caller eligibility + remaining-prize counts", "tags": [ "hunt" ], "parameters": [], "operationId": "hunt.status", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/hunt/oracle": { "get": { "summary": "Daily oracle riddle + answer fingerprint", "tags": [ "hunt" ], "parameters": [], "operationId": "hunt.oracle", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } } } } }, "/api/hunt/oracle/konami": { "get": { "summary": "Daily Konami token (only revealed with X-Konami-Sequence header)", "tags": [ "hunt" ], "parameters": [], "operationId": "hunt.oracleKonami", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/hunt/paths/{pathId}/submit": { "post": { "summary": "Submit a candidate answer for a hunt path", "tags": [ "hunt" ], "parameters": [ { "name": "pathId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "hunt.pathSubmit", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string", "minLength": 1 } }, "required": [ "answer" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/internal/digest/weekly-hiring-partners": { "get": { "summary": "Cron: weekly digest of pending hiring-partner applications", "tags": [ "internal" ], "parameters": [], "operationId": "internal.weeklyHiringPartnersDigestGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Cron: weekly digest of pending hiring-partner applications (POST form)", "tags": [ "internal" ], "parameters": [], "operationId": "internal.weeklyHiringPartnersDigestPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/internal/hunt/email-retry": { "get": { "summary": "Cron: retry undelivered treasure-hunt prize emails", "tags": [ "internal" ], "parameters": [], "operationId": "internal.huntEmailRetryGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Cron: retry undelivered treasure-hunt prize emails (POST form)", "tags": [ "internal" ], "parameters": [], "operationId": "internal.huntEmailRetryPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/internal/rate-limits/cleanup": { "post": { "summary": "Cron: delete expired rate-limit docs in batches", "tags": [ "internal" ], "parameters": [ { "name": "batchSize", "in": "query", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "maxBatches", "in": "query", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "dryRun", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "operationId": "internal.rateLimitsCleanup", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/internal/snapshots/rebuild": { "get": { "summary": "Cron: rebuild analytics + members snapshots", "tags": [ "internal" ], "parameters": [ { "name": "only", "in": "query", "schema": { "type": "string", "enum": [ "analytics", "members", "game-world", "game-world-3d", "all" ] } }, { "name": "force", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "operationId": "internal.snapshotsRebuildGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Cron: rebuild analytics + members snapshots (POST form)", "tags": [ "internal" ], "parameters": [ { "name": "only", "in": "query", "schema": { "type": "string", "enum": [ "analytics", "members", "game-world", "game-world-3d", "all" ] } }, { "name": "force", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "operationId": "internal.snapshotsRebuildPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/live/session": { "post": { "summary": "Admin: create a new live (lightning-talks) session", "tags": [ "live" ], "parameters": [], "operationId": "live.sessionCreate", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 120 } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "title": { "type": "string" }, "audiencePath": { "type": "string" }, "emceePath": { "type": "string" }, "status": { "type": "string" } }, "required": [ "sessionId", "title", "audiencePath", "emceePath", "status" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/live/{sessionId}/control": { "post": { "summary": "Emcee control deck: drive the session forward", "tags": [ "live" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "live.sessionControl", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "start-next", "pause-timer", "resume-timer", "complete-current", "skip-current", "remove-entry", "move-entry", "end-session" ] }, "entryId": { "type": "string" }, "targetIndex": { "type": "integer" } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "timerStatus": { "type": "string" }, "currentSpeaker": { "nullable": true }, "historyRecord": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "status", "timerStatus" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/live/{sessionId}/queue": { "post": { "summary": "Audience: join the speaker queue for a live session", "tags": [ "live" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "live.queueJoin", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "talkTitle": { "type": "string", "minLength": 1, "maxLength": 140 }, "durationMinutes": { "type": "number", "enum": [ 3, 5 ] } }, "required": [ "talkTitle", "durationMinutes" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "entryId": { "type": "string" }, "sessionId": { "type": "string" }, "talkTitle": { "type": "string" }, "durationMinutes": { "type": "number" }, "status": { "type": "string" } }, "required": [ "entryId", "sessionId", "talkTitle", "durationMinutes", "status" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/ludwitt/authorize": { "get": { "summary": "Begin Ludwitt OAuth (PKCE) — redirects to Ludwitt", "tags": [ "ludwitt" ], "parameters": [], "operationId": "ludwitt.authorize", "responses": { "302": { "description": "302", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } } }, "/api/ludwitt/connect-start": { "post": { "summary": "Authenticated PKCE handshake — returns the authorize URL", "tags": [ "ludwitt" ], "parameters": [], "operationId": "ludwitt.connectStart", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "returnTo": { "type": "string" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/ludwitt/finalize-token": { "post": { "summary": "Trade the one-time finalize cookie for the linked-account token", "tags": [ "ludwitt" ], "parameters": [], "operationId": "ludwitt.finalizeToken", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "410": { "description": "410", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/ludwitt/disconnect": { "post": { "summary": "Disconnect the Ludwitt link for the current user", "tags": [ "ludwitt" ], "parameters": [], "operationId": "ludwitt.disconnect", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/ludwitt/ai/messages": { "post": { "summary": "Proxy an Anthropic Messages-shaped request through Ludwitt", "tags": [ "ludwitt" ], "parameters": [], "operationId": "ludwitt.aiMessages", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "max_tokens": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "nullable": true } }, "required": [ "role" ] }, "minItems": 1 }, "system": { "type": "string" }, "temperature": { "type": "number" } }, "required": [ "model", "max_tokens", "messages" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/maintainers/status": { "get": { "summary": "Get the current user's maintainer eligibility", "tags": [ "maintainers" ], "parameters": [], "operationId": "maintainers.status", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/maintainers/review-queue": { "get": { "summary": "Get the open-PR review queue for the current maintainer", "tags": [ "maintainers" ], "parameters": [], "operationId": "maintainers.reviewQueue", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/members/public": { "get": { "summary": "Public, cached community members directory", "tags": [ "members" ], "parameters": [], "operationId": "members.publicList", "responses": { "200": { "description": "PublicMember[] — see types/members.ts", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "PublicMember[] — see types/members.ts" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/mentorship/matches": { "get": { "summary": "Get top mentor/mentee matches for the current user", "tags": [ "mentorship" ], "parameters": [], "operationId": "mentorship.matches", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/mentorship/profile": { "get": { "summary": "Get the current user's mentorship profile", "tags": [ "mentorship" ], "parameters": [], "operationId": "mentorship.profileGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Create or update the current user's mentorship profile", "tags": [ "mentorship" ], "parameters": [], "operationId": "mentorship.profilePost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "mentor", "mentee", "both" ] }, "expertise": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 }, "learningGoals": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 }, "preferredLanguages": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 }, "timezone": { "type": "string", "minLength": 1 }, "availability": { "type": "array", "items": { "nullable": true } }, "bio": { "type": "string", "maxLength": 1000 }, "maxMentees": { "type": "integer", "minimum": 1, "maximum": 10 }, "isActive": { "type": "boolean" } }, "required": [ "role", "timezone" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/mentorship/request": { "get": { "summary": "List the current user's mentorship requests", "tags": [ "mentorship" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "sent", "received" ] } } ], "operationId": "mentorship.requestGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Send a mentorship request to another user", "tags": [ "mentorship" ], "parameters": [], "operationId": "mentorship.requestPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "toUserId": { "type": "string", "minLength": 1 }, "goals": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 10 }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 }, "consentToShareProfile": { "type": "boolean", "enum": [ true ] } }, "required": [ "toUserId", "goals", "message", "consentToShareProfile" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/mentorship/respond": { "post": { "summary": "Accept or decline a received mentorship request", "tags": [ "mentorship" ], "parameters": [], "operationId": "mentorship.respond", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "accept", "decline" ] } }, "required": [ "requestId", "action" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/challenges/{challengeId}/submissions": { "post": { "summary": "Create a monthly challenge submission draft or submitted entry", "tags": [ "monthlyChallenges" ], "parameters": [ { "name": "challengeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "monthlyChallenges.createSubmission", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 3, "maxLength": 120 }, "summary": { "type": "string", "minLength": 20, "maxLength": 500 }, "repositoryUrl": { "type": "string", "format": "uri" }, "demoUrl": { "type": "string", "format": "uri" }, "writeup": { "type": "string", "minLength": 50, "maxLength": 4000 }, "cursorWorkflow": { "type": "string", "minLength": 20, "maxLength": 2000 }, "submitNow": { "type": "boolean" } }, "required": [ "title", "summary", "writeup", "cursorWorkflow" ] } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "submission": { "type": "object", "properties": { "id": { "type": "string" }, "challengeId": { "type": "string" }, "ownerUid": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "repositoryUrl": { "type": "string" }, "demoUrl": { "type": "string" }, "writeup": { "type": "string" }, "cursorWorkflow": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "submitted" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "submittedAt": { "type": "string" } }, "required": [ "id", "challengeId", "ownerUid", "title", "summary", "writeup", "cursorWorkflow", "status", "createdAt", "updatedAt" ] } }, "required": [ "ok", "submission" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/notifications/unsubscribe": { "get": { "summary": "One-click email unsubscribe (HMAC token in query)", "tags": [ "notifications" ], "parameters": [ { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "token", "in": "query", "schema": { "type": "string" } } ], "operationId": "notifications.unsubscribe", "responses": { "302": { "description": "302", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } } }, "/api/notify-admin/cfp": { "post": { "summary": "Email admin about a new CFP submission", "tags": [ "notifyAdmin" ], "parameters": [], "operationId": "notifyAdmin.cfp", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "school": { "type": "string" }, "department": { "type": "string" }, "advisor": { "type": "string" }, "thesisTitle": { "type": "string", "minLength": 1 }, "abstract": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "name", "email", "thesisTitle" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/notify-admin/event": { "post": { "summary": "Email admin about a new event request", "tags": [ "notifyAdmin" ], "parameters": [], "operationId": "notifyAdmin.event", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "organization": { "type": "string" }, "eventType": { "type": "string" }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "proposedDate": { "type": "string" }, "expectedAttendees": { "type": "string" }, "venue": { "type": "string" }, "additionalInfo": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "name", "email", "title" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/notify-admin/talk": { "post": { "summary": "Email admin about a new talk submission", "tags": [ "notifyAdmin" ], "parameters": [], "operationId": "notifyAdmin.talk", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "category": { "type": "string" }, "duration": { "type": "string" }, "experience": { "type": "string" }, "bio": { "type": "string" }, "linkedIn": { "type": "string" }, "twitter": { "type": "string" }, "previousTalks": { "type": "string" }, "submissionId": { "type": "string" } }, "required": [ "name", "email", "title" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/pair/matches": { "get": { "summary": "Get top pair-programming matches for the current user", "tags": [ "pair" ], "parameters": [], "operationId": "pair.matches", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/pair/profile": { "get": { "summary": "Get the current user's pair-programming profile", "tags": [ "pair" ], "parameters": [], "operationId": "pair.profileGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Create or update the current user's pair-programming profile", "tags": [ "pair" ], "parameters": [], "operationId": "pair.profilePost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "skillsCanTeach": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 20 }, "skillsWantToLearn": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 20 }, "preferredLanguages": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 20 }, "preferredFrameworks": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 20 }, "timezone": { "type": "string", "minLength": 1 }, "availability": { "type": "array", "items": { "nullable": true } }, "sessionTypes": { "type": "array", "items": { "type": "string", "enum": [ "teach-me", "build-together", "code-review", "explore-topic" ] }, "minItems": 1 }, "bio": { "type": "string", "maxLength": 1000 }, "isActive": { "type": "boolean" } }, "required": [ "skillsCanTeach", "skillsWantToLearn", "timezone", "sessionTypes" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/pair/request": { "get": { "summary": "List the current user's pair requests", "tags": [ "pair" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "sent", "received" ] } } ], "operationId": "pair.requestGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Send a pair request to another user", "tags": [ "pair" ], "parameters": [], "operationId": "pair.requestPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "toUserId": { "type": "string", "minLength": 1 }, "sessionType": { "type": "string", "enum": [ "teach-me", "build-together", "code-review", "explore-topic" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 }, "proposedTime": { "type": "string" } }, "required": [ "toUserId", "sessionType", "message" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/pair/respond": { "post": { "summary": "Accept or decline a received pair request", "tags": [ "pair" ], "parameters": [], "operationId": "pair.respond", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "accept", "decline" ] } }, "required": [ "requestId", "action" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/profile/data": { "get": { "summary": "Get the current user's profile data (with optional GDPR-portable export)", "tags": [ "profile" ], "parameters": [ { "name": "reconcileGithub", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "portable" ] } } ], "operationId": "profile.data", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/profile/github/reconcile": { "post": { "summary": "Reconcile merged-PR counts from the connected GitHub account", "tags": [ "profile" ], "parameters": [], "operationId": "profile.githubReconcile", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "githubLogin": { "type": "string" }, "mergedPrCount": { "type": "integer", "minimum": 0 }, "syncedPrCount": { "type": "integer", "minimum": 0 } }, "required": [ "success", "githubLogin", "mergedPrCount", "syncedPrCount" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/profile/subscription": { "get": { "summary": "Get the current user's email-subscription status", "tags": [ "profile" ], "parameters": [], "operationId": "profile.subscriptionGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "onList": { "type": "boolean" }, "subscribed": { "type": "boolean" } }, "required": [ "onList", "subscribed" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "summary": "Update the current user's email-subscription status", "tags": [ "profile" ], "parameters": [], "operationId": "profile.subscriptionPatch", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribed": { "type": "boolean" } }, "required": [ "subscribed" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribed": { "type": "boolean" } }, "required": [ "subscribed" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/profile/update": { "patch": { "summary": "Update the current user's profile fields", "tags": [ "profile" ], "parameters": [], "operationId": "profile.update", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "bio": { "type": "string" }, "location": { "type": "string" }, "company": { "type": "string" }, "jobTitle": { "type": "string" }, "socialLinks": { "type": "object", "properties": { "github": { "type": "string" }, "twitter": { "type": "string" }, "linkedin": { "type": "string" }, "website": { "type": "string" }, "substack": { "type": "string" } }, "additionalProperties": true } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "profile": { "type": "object", "properties": { "displayName": { "type": "string" }, "bio": { "type": "string" }, "location": { "type": "string" }, "company": { "type": "string" }, "jobTitle": { "type": "string" }, "socialLinks": { "type": "object", "properties": { "github": { "type": "string" }, "twitter": { "type": "string" }, "linkedin": { "type": "string" }, "website": { "type": "string" }, "substack": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } }, "required": [ "success", "profile" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/profile/visibility": { "get": { "summary": "Get the current user's profile visibility flags", "tags": [ "profile" ], "parameters": [], "operationId": "profile.visibilityGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "profile": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "profile" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "summary": "Update the current user's profile visibility flags", "tags": [ "profile" ], "parameters": [], "operationId": "profile.visibilityPatch", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "isPublic": { "type": "boolean" }, "showEmail": { "type": "boolean" }, "showBio": { "type": "boolean" }, "showLocation": { "type": "boolean" }, "showCompany": { "type": "boolean" }, "showJobTitle": { "type": "boolean" }, "showDiscord": { "type": "boolean" }, "showGithubBadge": { "type": "boolean" }, "showEventsAttended": { "type": "boolean" }, "showTalksGiven": { "type": "boolean" }, "showWebsite": { "type": "boolean" }, "showLinkedIn": { "type": "boolean" }, "showTwitter": { "type": "boolean" }, "showGithub": { "type": "boolean" }, "showSubstack": { "type": "boolean" }, "showMemberSince": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "visibility": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "success", "visibility" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/templates": { "post": { "summary": "Create a private prompt template draft or pending-review template", "tags": [ "promptTemplates" ], "parameters": [], "operationId": "promptTemplates.createTemplate", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 3, "maxLength": 120 }, "summary": { "type": "string", "minLength": 10, "maxLength": 500 }, "category": { "type": "string", "minLength": 2, "maxLength": 64 }, "useCase": { "type": "string", "minLength": 2, "maxLength": 120 }, "prompt": { "type": "string", "minLength": 20, "maxLength": 8000 }, "placeholders": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 240 }, "required": { "type": "boolean" }, "example": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "name", "label", "description", "required", "example" ] }, "maxItems": 20 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "submitForReview": { "type": "boolean" } }, "required": [ "title", "summary", "category", "prompt" ] } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "template": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "ownerUid": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string" }, "useCase": { "type": "string" }, "prompt": { "type": "string" }, "placeholders": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,48}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 240 }, "required": { "type": "boolean" }, "example": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "name", "label", "description", "required", "example" ] } }, "tags": { "type": "array", "items": { "type": "string" } }, "moderationStatus": { "type": "string", "enum": [ "draft", "pending_review" ] }, "visibility": { "type": "string", "enum": [ "private" ] }, "voteScore": { "type": "integer" }, "variantCount": { "type": "integer", "minimum": 0 }, "forkCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "slug", "ownerUid", "title", "summary", "category", "useCase", "prompt", "placeholders", "tags", "moderationStatus", "visibility", "voteScore", "variantCount", "forkCount", "createdAt", "updatedAt" ] } }, "required": [ "ok", "template" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/questions": { "get": { "summary": "List questions with cursor pagination", "tags": [ "questions" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "operationId": "questions.list", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "questions", "nextCursor", "hasMore" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/questions/{questionId}": { "get": { "summary": "Get question detail (with top answers + related cookbook entries)", "tags": [ "questions" ], "parameters": [ { "name": "questionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "questions.detail", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "object", "properties": {}, "additionalProperties": true }, "answers": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "relatedCookbook": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "question", "answers" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/questions/post": { "post": { "summary": "Create a new question", "tags": [ "questions" ], "parameters": [], "operationId": "questions.post", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 10, "maxLength": 200 }, "body": { "type": "string", "minLength": 20, "maxLength": 5000 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, "required": [ "title", "body" ] } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "type": "object", "properties": { "questionId": { "type": "string" } }, "required": [ "questionId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/questions/answer": { "post": { "summary": "Post an answer on a question", "tags": [ "questions" ], "parameters": [], "operationId": "questions.answer", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 20, "maxLength": 5000 } }, "required": [ "questionId", "body" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "answerId": { "type": "string" } }, "required": [ "answerId" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/questions/accept": { "post": { "summary": "Mark an answer as accepted (question owner only)", "tags": [ "questions" ], "parameters": [], "operationId": "questions.accept", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1 }, "answerId": { "type": "string", "minLength": 1 } }, "required": [ "questionId", "answerId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/questions/vote": { "post": { "summary": "Vote up/down on a question or answer", "tags": [ "questions" ], "parameters": [], "operationId": "questions.vote", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetType": { "type": "string", "enum": [ "question", "answer" ] }, "targetId": { "type": "string", "minLength": 1 }, "questionId": { "type": "string" }, "type": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "targetType", "targetId", "type" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "upvotes": { "type": "integer", "minimum": 0 }, "downvotes": { "type": "integer", "minimum": 0 }, "action": { "type": "string" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "get": { "summary": "Get the current user's votes (per target id)", "tags": [ "questions" ], "parameters": [], "operationId": "questions.myVotes", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "userVotes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "up", "down" ], "nullable": true } } }, "required": [ "userVotes" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/showcase/submission": { "get": { "summary": "Get the current user's showcase submissions", "tags": [ "showcase" ], "parameters": [], "operationId": "showcase.submissionList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissions": { "type": "array", "items": { "type": "object", "properties": { "projectId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } }, "required": [ "projectId", "status" ] } } }, "required": [ "submissions" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Submit a curated showcase project for moderation", "tags": [ "showcase" ], "parameters": [], "operationId": "showcase.submissionCreate", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "boolean" }, "resubmitted": { "type": "boolean" }, "projectId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } }, "required": [ "created", "projectId", "status" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/showcase/submission/approve": { "get": { "summary": "Admin: list pending showcase submissions", "tags": [ "showcase" ], "parameters": [], "operationId": "showcase.submissionPendingList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "pendingSubmissions": { "type": "array", "items": { "type": "object", "properties": { "submissionId": { "type": "string" }, "userId": { "type": "string" }, "projectId": { "type": "string" }, "createdAt": { "type": "string" }, "resubmittedAt": { "type": "string" } }, "required": [ "submissionId", "userId", "projectId" ], "additionalProperties": true } } }, "required": [ "pendingSubmissions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Admin: approve or reject a showcase submission", "tags": [ "showcase" ], "parameters": [], "operationId": "showcase.submissionApprove", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionId": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "submissionId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean" }, "rejected": { "type": "boolean" }, "alreadyApproved": { "type": "boolean" }, "submissionId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "approved", "submissionId", "status" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/showcase/vote": { "post": { "summary": "Vote on a showcase project (toggle / switch supported)", "tags": [ "showcase" ], "parameters": [], "operationId": "showcase.vote", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "projectId", "type" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "added", "removed", "switched" ] }, "type": { "type": "string", "enum": [ "up", "down" ] }, "previousType": { "type": "string", "enum": [ "up", "down" ] }, "upCount": { "type": "integer", "minimum": 0 }, "downCount": { "type": "integer", "minimum": 0 } }, "required": [ "action", "type", "upCount", "downCount" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "get": { "summary": "Get aggregate showcase project vote counts (paginated) and user's ledger", "tags": [ "showcase" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 50, max 200", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "startAfter", "in": "query", "description": "Cursor doc id (showcase project id)", "schema": { "type": "string" } } ], "operationId": "showcase.voteList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "votes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "upCount": { "type": "integer", "minimum": 0 }, "downCount": { "type": "integer", "minimum": 0 } }, "required": [ "upCount", "downCount" ] } }, "userVotes": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "votes", "userVotes" ] } } } } } } }, "/api/skills/progress": { "get": { "summary": "Get the current user's Skills Passport progress", "tags": [ "skills" ], "parameters": [], "operationId": "skills.progress", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "trackId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "levels": { "type": "array", "items": { "type": "string", "enum": [ "started", "practiced", "verified", "mentor" ] } }, "evidenceRequirements": { "type": "array", "items": { "type": "string" } }, "relatedBadgeIds": { "type": "array", "items": { "type": "string", "enum": [ "first-steps", "connected", "speaker", "hacker", "showcase-star", "conversation-starter", "regular", "mentor", "contributor" ] } } }, "required": [ "id", "trackId", "title", "description", "levels", "evidenceRequirements", "relatedBadgeIds" ] } }, "progress": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string" }, "trackId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "level": { "type": "string", "enum": [ "started", "practiced", "verified", "mentor" ] }, "progressPercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "relatedBadgeIds": { "type": "array", "items": { "type": "string", "enum": [ "first-steps", "connected", "speaker", "hacker", "showcase-star", "conversation-starter", "regular", "mentor", "contributor" ] } }, "earnedBadgeIds": { "type": "array", "items": { "type": "string", "enum": [ "first-steps", "connected", "speaker", "hacker", "showcase-star", "conversation-starter", "regular", "mentor", "contributor" ] } }, "evidenceRequirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "skillId", "trackId", "title", "description", "level", "progressPercent", "relatedBadgeIds", "earnedBadgeIds", "evidenceRequirements" ] } }, "summary": { "type": "object", "properties": { "totalSkills": { "type": "integer", "minimum": 0 }, "practicedSkills": { "type": "integer", "minimum": 0 }, "verifiedSkills": { "type": "integer", "minimum": 0 }, "mentorSkills": { "type": "integer", "minimum": 0 }, "averageProgressPercent": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "totalSkills", "practicedSkills", "verifiedSkills", "mentorSkills", "averageProgressPercent" ] }, "badgeDataStatus": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "complete", "partial", "failed" ] }, "isAuthoritative": { "type": "boolean" }, "failedSources": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": [ "state", "isAuthoritative", "failedSources" ] } }, "required": [ "catalog", "progress", "summary", "badgeDataStatus" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/apply": { "get": { "summary": "Get the current user's summer-cohort application + counts", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.applyGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Create or update the current user's summer-cohort application", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.applyPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "minLength": 1, "maxLength": 50 }, "cohorts": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "isLocal": { "type": "boolean" }, "wantsToPresent": { "type": "boolean" } }, "required": [ "name", "phone", "cohorts", "isLocal", "wantsToPresent" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "summary": "Withdraw the current user's summer-cohort application", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.applyDelete", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/withdraw": { "get": { "summary": "One-click cohort withdrawal (HMAC token in query)", "tags": [ "summerCohort" ], "parameters": [ { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "cohortId", "in": "query", "schema": { "type": "string" } }, { "name": "token", "in": "query", "schema": { "type": "string" } } ], "operationId": "summerCohort.withdraw", "responses": { "302": { "description": "302", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } } }, "/api/summer-cohort/confirm-dev-env": { "post": { "summary": "Admitted cohort participant confirms dev environment is set up (Node + Git + IDE)", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.confirmDevEnv", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "cohort1DevEnvConfirmedAt": { "type": "integer", "minimum": 0 } }, "required": [ "ok", "cohort1DevEnvConfirmedAt" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/intake-survey": { "get": { "summary": "Get the current user's intake-survey response", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.intakeSurveyGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Submit (or re-submit) the intake survey", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.intakeSurveyPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/submissions/{weekId}": { "get": { "summary": "Public read of merged submissions on a vote-format week", "tags": [ "summerCohort" ], "parameters": [ { "name": "weekId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "operationId": "summerCohort.submissionsByWeek", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } } }, "/api/summer-cohort/my-score/{weekId}": { "get": { "summary": "Return only the calling user's own AI-judge score for a vote-format week — other users' scores are never exposed by this endpoint", "tags": [ "summerCohort" ], "parameters": [ { "name": "weekId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "cohortId", "in": "query", "schema": { "type": "string", "enum": [ "cohort-1", "cohort-2" ] } } ], "operationId": "summerCohort.myScoreByWeek", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/votes": { "get": { "summary": "Aggregate vote counts for a vote-format week", "tags": [ "summerCohort" ], "parameters": [ { "name": "weekId", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "week-1", "week-2", "week-3" ] } }, { "name": "cohortId", "in": "query", "schema": { "type": "string", "enum": [ "cohort-1", "cohort-2" ] } } ], "operationId": "summerCohort.votesGet", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } } }, "post": { "summary": "Toggle the current user's vote for a submission", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.votesPost", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "weekId": { "type": "string", "enum": [ "week-1", "week-2", "week-3" ] }, "submitterHandle": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_-]+$" }, "cohortId": { "type": "string", "enum": [ "cohort-1", "cohort-2" ] } }, "required": [ "weekId", "submitterHandle" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/admin/access": { "get": { "summary": "Probe whether the current user is allowed in the Summer Cohort admin area", "tags": [ "summerCohort" ], "parameters": [], "operationId": "summerCohort.adminAccess", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/admin/applications": { "get": { "summary": "List applications (admin only) with optional cohort/status filter", "tags": [ "summerCohort" ], "parameters": [ { "name": "cohortId", "in": "query", "schema": { "type": "string", "enum": [ "cohort-1", "cohort-2" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "admitted", "rejected", "waitlist" ] } } ], "operationId": "summerCohort.adminApplications", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/summer-cohort/admin/intake-aggregates": { "get": { "summary": "Aggregate stats for intake-survey responses (admin only, no PII or free text)", "tags": [ "summerCohort" ], "parameters": [ { "name": "cohort", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "operationId": "summerCohort.adminIntakeAggregates", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/talks/submission/moderate": { "get": { "summary": "Admin: list talk submissions (paginated by status, or three-bucket default)", "tags": [ "talks" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size; default 20, max 100", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Single-status paginated mode; omit to get all three buckets", "schema": { "type": "string", "enum": [ "pending", "approved", "completed" ] } } ], "operationId": "talks.submissionModerateList", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "talkSubmissions": { "type": "array", "items": { "type": "object", "properties": { "submissionId": { "type": "string" }, "userId": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "submissionId", "userId", "title", "status" ], "additionalProperties": true } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if there are no more", "nullable": true }, "hasMore": { "type": "boolean", "description": "True if more items exist beyond this page" } }, "required": [ "talkSubmissions", "nextCursor", "hasMore" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "summary": "Admin: approve a talk submission or mark it delivered", "tags": [ "talks" ], "parameters": [], "operationId": "talks.submissionModerateAction", "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionId": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "approve", "complete" ] } }, "required": [ "submissionId" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean" }, "submissionId": { "type": "string" }, "status": { "type": "string" }, "alreadyApproved": { "type": "boolean" }, "alreadyCompleted": { "type": "boolean" } }, "required": [ "approved", "submissionId", "status" ], "additionalProperties": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfterSeconds": { "type": "integer", "minimum": 0 } }, "required": [ "error" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "RATE_LIMITED", "CONFLICT", "SERVER_ERROR", "NOT_CONFIGURED" ] } }, "required": [ "message", "code" ] } }, "required": [ "success", "error" ] } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } } }, "info": { "title": "Cursor Boston API", "version": "0.1.0", "description": "REST API for the Cursor Boston community platform. See https://github.com/rogerSuperBuilderAlpha/cursor-boston for source. Authentication uses Firebase Auth ID tokens (Bearer) or session cookies.", "license": { "name": "GPL-3.0", "url": "https://www.gnu.org/licenses/gpl-3.0.html" }, "contact": { "name": "Cursor Boston", "url": "https://github.com/rogerSuperBuilderAlpha/cursor-boston" } }, "servers": [ { "url": "https://cursorboston.com", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local dev" } ], "tags": [ { "name": "agents", "description": "Programmatic agent registration, claiming, and self-service" }, { "name": "analytics", "description": "Public aggregate analytics snapshots" }, { "name": "auth", "description": "Authentication and email resolution" }, { "name": "badges", "description": "Badge definitions and per-user awards" }, { "name": "certificate", "description": "Verifiable merged-PR certificates" }, { "name": "cfp", "description": "CFP graduate-student .edu email verification" }, { "name": "community", "description": "Community posts, replies, reactions, moderation" }, { "name": "cookbook", "description": "Prompt cookbook entries and votes" }, { "name": "discord", "description": "Discord OAuth (link / unlink)" }, { "name": "events", "description": "Coworking sessions and PyData 2026 ticketing" }, { "name": "game", "description": "Strategy game endpoints (leaderboard, attacks, artifacts, turns)" }, { "name": "github", "description": "GitHub OAuth + signed webhook receiver" }, { "name": "hackathons", "description": "Hackathon pool, teams, submissions, and Hack-a-Sprint showcase" }, { "name": "health", "description": "Liveness probe" }, { "name": "hiring-partners", "description": "Hiring-partner application intake" }, { "name": "hunt", "description": "Treasure hunt: oracle, paths, prize claim" }, { "name": "internal", "description": "Cron-secret-protected maintenance endpoints" }, { "name": "live", "description": "Live lightning-talks sessions, emcee control, and audience queue" }, { "name": "ludwitt", "description": "Ludwitt OAuth + AI proxy through the shared credit pool" }, { "name": "maintainers", "description": "Maintainer self-service and review queue" }, { "name": "members", "description": "Public community members directory" }, { "name": "mentorship", "description": "Mentor/mentee profiles, matches, requests" }, { "name": "notifications", "description": "Email unsubscribe (HMAC token)" }, { "name": "notify-admin", "description": "Email-relay endpoints for public submission forms" }, { "name": "pair", "description": "Pair-programming profiles, matches, requests" }, { "name": "account", "description": "Account lifecycle: GDPR delete, scheduled purge" }, { "name": "profile", "description": "User profile: data, visibility, subscription, GitHub reconcile" }, { "name": "questions", "description": "Q&A: questions, answers, votes, accept" }, { "name": "showcase", "description": "Showcase project submissions, moderation, and votes" }, { "name": "summer-cohort", "description": "Summer Cohort applications, intake survey, voting" }, { "name": "talks", "description": "Talk-submission moderation queue" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Firebase ID token", "description": "Firebase Auth ID token. Obtain via Firebase Auth client SDK and pass as `Authorization: Bearer `." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "session", "description": "Session cookie set by /api/auth/* during sign-in." } } } }