{"openapi":"3.1.0","info":{"title":"Supercraft Agentic API","description":"Unified API for AI agents to manage game server hosting on Supercraft.","version":"0.1.0"},"paths":{"/auth/login-link":{"post":{"tags":["auth"],"summary":"Login Link","description":"Generate a magic login link for an existing user.","operationId":"login_link_auth_login_link_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginLinkRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/claim":{"get":{"tags":["auth"],"summary":"Claim","description":"Exchange a magic token for a JWT. Poll this every 5s after giving the user a checkout/login URL.","operationId":"claim_auth_claim_get","parameters":[{"name":"magic","in":"query","required":true,"schema":{"type":"string","title":"Magic"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/reset-password":{"post":{"tags":["auth"],"summary":"Reset Password","description":"Trigger a WordPress password reset email. Always returns 200 (prevents email enumeration).","operationId":"reset_password_auth_reset_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/refresh":{"post":{"tags":["auth"],"summary":"Refresh","description":"Refresh a valid JWT.","operationId":"refresh_auth_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/auth/whoami":{"get":{"tags":["auth"],"summary":"Whoami","description":"Get current authenticated user info.","operationId":"whoami_auth_whoami_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/catalog/games":{"get":{"tags":["catalog"],"summary":"List Games","description":"List all available games with game codes and links to full descriptions.","operationId":"list_games_catalog_games_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/catalog/games/{game_code}":{"get":{"tags":["catalog"],"summary":"Get Game","description":"Get full plan and pricing details for a specific game.","operationId":"get_game_catalog_games__game_code__get","parameters":[{"name":"game_code","in":"path","required":true,"schema":{"type":"string","title":"Game Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/catalog/regions":{"get":{"tags":["catalog"],"summary":"List Regions","description":"List available server regions.","operationId":"list_regions_catalog_regions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/dedicated-servers/index.md":{"get":{"tags":["catalog"],"summary":"Get Offer Index","description":"Render the offer index page listing all games.","operationId":"get_offer_index_dedicated_servers_index_md_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/documentation-for-agents/getting-started.md":{"get":{"tags":["catalog"],"summary":"Get Getting Started","description":"Render the getting started guide with dynamic game list.","operationId":"get_getting_started_documentation_for_agents_getting_started_md_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/{slug}-server-api":{"get":{"tags":["catalog"],"summary":"Get Game Api Guide","description":"Render game-specific API guide (e.g. /valheim-server-api).","operationId":"get_game_api_guide__slug__server_api_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/dedicated-servers/{slug}-server-hosting-offer.md":{"get":{"tags":["catalog"],"summary":"Get Offer Page","description":"Render game offer page from Jinja template with live pricing data.","operationId":"get_offer_page_dedicated_servers__slug__server_hosting_offer_md_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orders/purchase":{"post":{"tags":["orders"],"summary":"Purchase","description":"Generate a checkout URL with a magic token for seamless purchase + authentication.","operationId":"purchase_orders_purchase_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers":{"get":{"tags":["servers"],"summary":"List Servers","description":"List all servers for the authenticated user.","operationId":"list_servers_servers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/servers/{server_id}":{"get":{"tags":["servers"],"summary":"Get Server","description":"Get detailed server status including live run_status from agent.","operationId":"get_server_servers__server_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/install":{"post":{"tags":["servers"],"summary":"Install Game","description":"Install game on a server that has no active deployment.","operationId":"install_game_servers__server_id__install_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/start":{"post":{"tags":["servers"],"summary":"Start Server","description":"Start the server.","operationId":"start_server_servers__server_id__start_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/stop":{"post":{"tags":["servers"],"summary":"Stop Server","description":"Stop the server.","operationId":"stop_server_servers__server_id__stop_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/restart":{"post":{"tags":["servers"],"summary":"Restart Server","description":"Restart the server.","operationId":"restart_server_servers__server_id__restart_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/config":{"get":{"tags":["servers"],"summary":"Get Config","description":"Get current server configuration.","operationId":"get_config_servers__server_id__config_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["servers"],"summary":"Update Config","description":"Update server configuration. Partial updates supported — only send fields you want to change.","operationId":"update_config_servers__server_id__config_put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/config/schema":{"get":{"tags":["servers"],"summary":"Get Config Schema","description":"Get the configuration schema for this game.\n\nReturns the JSON Schema from the agent's dedicated config/schema endpoint.\nThe agent returns {status, game, config_schema: {...}}.\n\nNote: config schema, config read/write, start, stop and console are only\navailable once the game has finished installing (status != INSTALLING/PENDING).","operationId":"get_config_schema_servers__server_id__config_schema_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/connection":{"get":{"tags":["servers"],"summary":"Get Connection","description":"Get connection details for the server (host, port, password, etc.).","operationId":"get_connection_servers__server_id__connection_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/console":{"post":{"tags":["servers"],"summary":"Send Console Command","description":"Send a console/RCON command.","operationId":"send_console_command_servers__server_id__console_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsoleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/logs":{"get":{"tags":["servers"],"summary":"Get Logs","description":"Get recent server logs.","operationId":"get_logs_servers__server_id__logs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}},{"name":"lines","in":"query","required":false,"schema":{"type":"integer","maximum":500,"default":100,"title":"Lines"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/available-games":{"get":{"tags":["servers"],"summary":"Get Available Games","description":"Get games and branches available for this server's plan.","operationId":"get_available_games_servers__server_id__available_games_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/servers/{server_id}/switch-game":{"post":{"tags":["servers"],"summary":"Switch Game","description":"Switch to a different game. WARNING: wipes current game data.","operationId":"switch_game_servers__server_id__switch_game_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"server_id","in":"path","required":true,"schema":{"type":"integer","title":"Server Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwitchGameRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/guides/":{"get":{"tags":["guides"],"summary":"List Guides","description":"List available guides.","operationId":"list_guides_guides__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/guides/{path}":{"get":{"tags":["guides"],"summary":"Get Guide","description":"Returns raw markdown content for a guide.","operationId":"get_guide_guides__path__get","parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string","title":"Path"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/fulfill-magic":{"post":{"tags":["internal"],"summary":"Fulfill Magic","description":"Called by WP webhook when payment completes or user logs in via magic link.\nWP must send x-internal-key header matching WP_API_KEY.","operationId":"fulfill_magic_internal_fulfill_magic_post","parameters":[{"name":"x-internal-key","in":"header","required":true,"schema":{"type":"string","title":"X-Internal-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/test-simulate-payment":{"post":{"tags":["internal"],"summary":"Test Simulate Payment","description":"TEST ONLY - Simulates a successful payment by fulfilling a magic token directly.\nDisabled in production (SUPERCRAFT_PROD). Used by agentic-api-qa agent for automated testing.\n\nThis bypasses WP entirely — use when testing the agentic API in isolation.\nFor full-stack testing (with WP), call WP's POST /wp-json/supercraft/v1/test/simulate-payment instead.","operationId":"test_simulate_payment_internal_test_simulate_payment_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulatePaymentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/clear-catalog-cache":{"post":{"tags":["internal"],"summary":"Clear Catalog Cache","description":"Clear the in-memory catalog cache so next request fetches fresh data from midserver.","operationId":"clear_catalog_cache_internal_clear_catalog_cache_post","parameters":[{"name":"key","in":"query","required":true,"schema":{"type":"string","title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/index.md":{"get":{"summary":"Root Index Md","operationId":"root_index_md_index_md_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"summary":"Llms Txt","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/robots.txt":{"get":{"summary":"Robots Txt","operationId":"robots_txt_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/d0acda3a8bed4b1a997e79f5f0a53ce4.txt":{"get":{"summary":"Indexnow Key","operationId":"indexnow_key_d0acda3a8bed4b1a997e79f5f0a53ce4_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"summary":"Sitemap Xml","description":"Generate sitemap.xml on the fly from registered routes.\n\nIncludes only GET endpoints under /catalog/, /dedicated-servers/, /documentation-for-agents/,\nplus the root, openapi.json, and per-game /{slug}-server-api endpoints.","operationId":"sitemap_xml_sitemap_xml_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"ConfigUpdateRequest":{"properties":{"config":{"additionalProperties":true,"type":"object","title":"Config"}},"type":"object","required":["config"],"title":"ConfigUpdateRequest"},"ConsoleRequest":{"properties":{"command":{"type":"string","title":"Command"}},"type":"object","required":["command"],"title":"ConsoleRequest"},"FulfillRequest":{"properties":{"magic":{"type":"string","title":"Magic"},"user_id":{"type":"integer","title":"User Id"},"email":{"type":"string","title":"Email"},"name":{"type":"string","title":"Name","default":""},"app_password":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"App Password"}},"type":"object","required":["magic","user_id","email"],"title":"FulfillRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InstallRequest":{"properties":{"game":{"type":"string","title":"Game"},"region":{"type":"string","title":"Region"},"branch":{"type":"string","title":"Branch","default":"stable"}},"type":"object","required":["game","region"],"title":"InstallRequest"},"LoginLinkRequest":{"properties":{"email":{"type":"string","title":"Email"}},"type":"object","required":["email"],"title":"LoginLinkRequest"},"PurchaseRequest":{"properties":{"product_id":{"type":"integer","title":"Product Id"}},"type":"object","required":["product_id"],"title":"PurchaseRequest"},"ResetPasswordRequest":{"properties":{"email":{"type":"string","title":"Email"}},"type":"object","required":["email"],"title":"ResetPasswordRequest"},"SimulatePaymentRequest":{"properties":{"magic":{"type":"string","title":"Magic"},"email":{"type":"string","title":"Email","default":"agentic-qa-test@supercraft.host"},"user_id":{"type":"integer","title":"User Id","default":99999},"name":{"type":"string","title":"Name","default":"QA Test User"}},"type":"object","required":["magic"],"title":"SimulatePaymentRequest"},"SwitchGameRequest":{"properties":{"game":{"type":"string","title":"Game"},"region":{"type":"string","title":"Region"},"branch":{"type":"string","title":"Branch","default":"stable"}},"type":"object","required":["game","region"],"title":"SwitchGameRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}