{"name":"Thrones of Aether Cloudflare API","apiVersion":"v2","protocolVersion":5,"storage":"Cloudflare D1","documentation":"/docs.html","versions":{"v1":{"status":"stable","description":"Compatibility routes for existing AI clients."},"v2":{"status":"current","description":"Multi-client API, website players, usage metrics, and detailed discovery."}},"clientTypes":["website","mobile_app","desktop_app","desktop_local_game","discord_social_sdk","ai_client","discord_bot","toa_discord_bot","community_tool","stats_dashboard"],"authentication":{"session":"Bearer toa_session_... for website/mobile/desktop users","apiKey":"Bearer toa_key_... for AI clients, bots, tools, and dashboards","controller":"Bearer toa_controller_... for direct AI seat control","host":"x-host-key header for the authoritative simulation host"},"rateLimitsPerMinute":{"anonymous":60,"website":240,"mobile_app":300,"desktop_app":300,"desktop_local_game":360,"discord_social_sdk":360,"ai_client":600,"discord_bot":360,"toa_discord_bot":480,"community_tool":300,"stats_dashboard":600,"host":3000},"roles":{"member":["account:read","account:update","keys:manage","chat:write"],"supporter":["account:read","account:update","keys:manage","chat:write"],"ai_controller":["account:read","account:update","ai:join","keys:manage","chat:write"],"news_poster":["account:read","account:update","keys:manage","chat:write","news:write"],"moderator":["account:read","account:update","accounts:list","sessions:view","chat:write","chat:moderate","news:write","news:manage"],"admin":["account:read","account:update","ai:join","keys:manage","accounts:list","sessions:view","roles:manage","accounts:secure","chat:write","chat:moderate","news:write","news:manage"],"developer":["account:read","account:update","ai:join","keys:manage","accounts:list","sessions:view","roles:manage","accounts:secure","chat:write","chat:moderate","news:write","news:manage"]},"community":["profiles","directory","search","badges","achievements","notifications","activity","realm_chat","partner_banners","png_avatar_uploads"],"actions":["pass","recruit","garrison","upgrade","city","economy","claim","attack","citadel"],"endpoints":[{"path":"/api/v2","method":"GET","auth":"none","permission":null,"description":"API discovery document."},{"path":"/api/v2/status","method":"GET","auth":"none","permission":null,"description":"Service, host, and controller status."},{"path":"/api/v2/legal","method":"GET","auth":"none","permission":null,"description":"Read current Terms and Privacy versions required for registration."},{"path":"/api/v2/client-config","method":"GET","auth":"none","permission":null,"description":"Read public native-client settings, including Discord Social SDK readiness."},{"path":"/api/v2/discord/oauth/exchange","method":"POST","auth":"session","permission":"account:read","description":"Exchange a Discord OAuth callback code for the signed-in user's Discord identity.","example":{"code":"discord-code","redirectUri":"https://example.com/discord-callback.html"}},{"path":"/api/v2/community-stats","method":"GET","auth":"none","permission":null,"description":"Public community counters for Discord and dashboards."},{"path":"/api/v2/accounts/register","method":"POST","auth":"none","permission":null,"description":"Create a user account.","example":{"username":"new_ruler","displayName":"New Ruler","password":"strong private password","referralCode":"ABC123"}},{"path":"/api/v2/accounts/login","method":"POST","auth":"none","permission":null,"description":"Create a 30-day app or website session.","example":{"username":"new_ruler","password":"strong private password"}},{"path":"/api/v2/accounts/me","method":"GET","auth":"session or API key","permission":"account:read","description":"Read the authenticated profile and credentials."},{"path":"/api/v2/accounts/export","method":"GET","auth":"session or API key","permission":"account:read","description":"Export your own account, gameplay, API usage, and community data without secrets."},{"path":"/api/v2/accounts/gamejolt/sync-trophies","method":"POST","auth":"session","permission":"account:read","description":"Award mapped Game Jolt trophies for earned TOA badges."},{"path":"/api/v2/accounts/api-keys","method":"POST","auth":"session","permission":"keys:manage","description":"Create a typed client API key.","example":{"name":"TOA Discord Bot","clientType":"toa_discord_bot"}},{"path":"/api/v2/world-power","method":"GET","auth":"session","permission":"account:read","description":"Read your persistent non-season world-map power and leaderboard."},{"path":"/api/v2/world-power/action","method":"POST","auth":"session","permission":"account:read","description":"Gain persistent world-map power. This does not affect season power.","example":{"action":"train"}},{"path":"/api/v2/daily-streak","method":"GET","auth":"session","permission":"account:read","description":"Read your daily login streak and claim status."},{"path":"/api/v2/daily-streak/claim","method":"POST","auth":"session","permission":"account:read","description":"Claim daily fake coins and persistent world power."},{"path":"/api/v2/users?q=NAME","method":"GET","auth":"none","permission":null,"description":"Search the public user directory."},{"path":"/api/v2/users/:username","method":"GET","auth":"none","permission":null,"description":"Read one public profile."},{"path":"/api/v2/activity","method":"GET","auth":"none","permission":null,"description":"Read public community activity."},{"path":"/api/v2/chat","method":"GET","auth":"session or API key","permission":"account:read","description":"Read up to 100 Realm Chat messages."},{"path":"/api/v2/chat","method":"POST","auth":"session or API key","permission":"chat:write","description":"Send a Realm Chat message.","example":{"message":"Ready for the next season?"}},{"path":"/api/v2/chat/:id","method":"DELETE","auth":"session or API key","permission":"owner or chat:moderate","description":"Delete your own message, or moderate any message."},{"path":"/api/v2/notifications","method":"GET","auth":"session","permission":"account:read","description":"Read private notifications."},{"path":"/api/v2/badges","method":"GET","auth":"none","permission":null,"description":"List badge definitions and holder counts."},{"path":"/api/v2/partners","method":"GET","auth":"none","permission":null,"description":"List clickable site partner banners."},{"path":"/api/v2/admin/partners","method":"POST","auth":"session","permission":"roles:manage","description":"Create a partner banner with a PNG image and HTTPS link."},{"path":"/api/v2/admin/partners/:id","method":"DELETE","auth":"session","permission":"roles:manage","description":"Delete a partner banner."},{"path":"/api/v2/alliances","method":"GET","auth":"none","permission":null,"description":"List human-founded alliances."},{"path":"/api/v2/alliances/invites/me","method":"GET","auth":"session","permission":"account:read","description":"List pending alliance invitations for the signed-in user."},{"path":"/api/v2/alliances/:id/invites","method":"POST","auth":"session","permission":"alliance owner","description":"Invite a user to an alliance.","example":{"username":"ruler_name"}},{"path":"/api/v2/alliances/:id/invites/accept","method":"POST","auth":"session","permission":"invited user","description":"Accept an alliance invitation."},{"path":"/api/v2/alliances/:id/invites/decline","method":"POST","auth":"session","permission":"invited user","description":"Decline an alliance invitation."},{"path":"/api/v2/alliances/:id","method":"PATCH","auth":"session","permission":"alliance owner","description":"Update alliance name, tag, or description."},{"path":"/api/v2/alliances/:id/members/:accountId","method":"DELETE","auth":"session","permission":"alliance owner","description":"Remove a member from an alliance."},{"path":"/api/v2/alliances/:id/owner","method":"PATCH","auth":"session","permission":"alliance owner","description":"Transfer alliance ownership to a current member.","example":{"accountId":"member_account_id"}},{"path":"/api/v2/alliances/:id/season-signup","method":"POST","auth":"session","permission":"alliance owner","description":"Enroll every current alliance member in the open season."},{"path":"/api/v2/alliances/:id/season-signup","method":"DELETE","auth":"session","permission":"alliance owner","description":"Withdraw the alliance roster before the season starts."},{"path":"/api/v2/world-map","method":"GET","auth":"none","permission":null,"description":"Read the persistent public alliance world map."},{"path":"/api/v2/world-map/territories/:id","method":"GET","auth":"none","permission":null,"description":"Read one public territory."},{"path":"/api/v2/alliances/:id/world","method":"GET","auth":"none","permission":null,"description":"Read public persistent-world alliance profile."},{"path":"/api/v2/alliances/:id/dashboard","method":"GET","auth":"session/API key","permission":"alliance member","description":"Read private alliance world dashboard, treasury, inventory, and operations."},{"path":"/api/v2/alliances/:id/capital","method":"POST","auth":"session/API key","permission":"alliance leader/co-leader","description":"Set one owned territory as the alliance capital.","example":{"territoryId":"northwatch"}},{"path":"/api/v2/alliances/:id/shop/purchase","method":"POST","auth":"session/API key","permission":"leader/co-leader/treasurer","description":"Buy alliance-owned war items with private War Supplies.","example":{"itemKey":"recon_report","quantity":1}},{"path":"/api/v2/alliances/:id/items/:itemKey/use","method":"POST","auth":"session/API key","permission":"leader/co-leader/general/treasurer","description":"Use an alliance item such as Recon Report or Emergency Broadcast.","example":{"territoryId":"northwatch","invasionId":"uuid"}},{"path":"/api/v2/invasions/schedule","method":"POST","auth":"session/API key","permission":"leader/co-leader/general","description":"Schedule a persistent-world invasion for staff review.","example":{"attackerAllianceId":"alliance_id","territoryId":"northwatch","scheduledAt":"2026-07-01T18:00:00.000Z"}},{"path":"/api/v2/invasions/upcoming","method":"GET","auth":"none","permission":null,"description":"List approved/active public invasions."},{"path":"/api/v2/invasions/:id","method":"GET","auth":"none","permission":null,"description":"Read an invasion and its public battle state."},{"path":"/api/v2/invasions/:id/checkin","method":"POST","auth":"session/API key","permission":"alliance member","description":"Check into an active invasion for your alliance."},{"path":"/api/v2/invasions/:id/action","method":"POST","auth":"session/API key","permission":"checked-in alliance member","description":"Submit a text battle action: attack, defend, or rally.","example":{"action":"attack"}},{"path":"/api/v2/wars","method":"GET","auth":"none","permission":null,"description":"List public pending, active, and recent persistent-world wars with War Terms."},{"path":"/api/v2/wars/:id","method":"GET","auth":"none","permission":null,"description":"Read one public persistent-world war with proposed and approved War Terms."},{"path":"/api/v2/wars/declare","method":"POST","auth":"session/API key","permission":"leader/co-leader/general/diplomat","description":"Request staff approval for an alliance war, optionally with proposed War Terms.","example":{"attackerAllianceId":"one","defenderAllianceId":"two","proposedTerms":"No raids during training events."}},{"path":"/api/v2/land-transfers","method":"POST","auth":"session/API key","permission":"leader/co-leader/diplomat","description":"Offer a territory transfer to another alliance.","example":{"territoryId":"northwatch","toAllianceId":"target"}},{"path":"/api/v2/land-transfers/:id/accept","method":"POST","auth":"session/API key","permission":"receiving alliance leader/co-leader","description":"Accept a pending land transfer."},{"path":"/api/v2/admin/world","method":"GET","auth":"session","permission":"roles:manage","description":"Staff validation queue and private world moderation snapshot."},{"path":"/api/v2/admin/invasions/:id/approve","method":"POST","auth":"session","permission":"roles:manage","description":"Approve an invasion, optionally with conditions.","example":{"conditions":"Small alliance gets fortification bonus."}},{"path":"/api/v2/admin/invasions/:id/deny","method":"POST","auth":"session","permission":"roles:manage","description":"Deny an invasion with a reason.","example":{"reason":"Invalid timing."}},{"path":"/api/v2/admin/wars/:id/approve","method":"POST","auth":"session","permission":"roles:manage","description":"Approve a pending war."},{"path":"/api/v2/admin/wars/:id/deny","method":"POST","auth":"session","permission":"roles:manage","description":"Invalidate or deny a pending war."},{"path":"/api/v2/admin/territories/:id","method":"POST","auth":"session","permission":"roles:manage","description":"Edit/assign a persistent-world territory."},{"path":"/api/v2/admin/alliances/:id/war-supplies","method":"POST","auth":"session","permission":"roles:manage","description":"Adjust private alliance War Supplies.","example":{"amount":100,"reason":"event reward"}},{"path":"/api/v2/admin/developer/world-map/territories","method":"POST","auth":"session","permission":"developer","description":"Create or update a persistent-world territory definition.","example":{"id":"newhold","name":"Newhold","x":50,"y":50,"adjacentIds":["northwatch"]}},{"path":"/api/v2/admin/developer/world-map/territories/:id","method":"DELETE","auth":"session","permission":"developer","description":"Remove an unowned persistent-world territory definition."},{"path":"/api/v2/admin/developer/world-map/seed","method":"POST","auth":"session","permission":"developer","description":"Upsert the default expanded map territory pack."},{"path":"/api/v2/news","method":"GET","auth":"optional session","permission":null,"description":"List news posts. Protected posts return locked metadata unless your session has the required role."},{"path":"/api/v2/news","method":"POST","auth":"session","permission":"news:write","description":"Publish public, passcode-protected, or role-protected news.","example":{"title":"Update","content":"Patch notes","categoryId":"general","visibility":"role","requiredRole":"supporter"}},{"path":"/api/v2/news/:id/unlock","method":"POST","auth":"none","permission":null,"description":"Unlock a passcode-protected news post.","example":{"passcode":"shared-code"}},{"path":"/api/v2/news/categories","method":"POST","auth":"session","permission":"news:manage","description":"Create a news category."},{"path":"/api/v2/seasons/lobby","method":"GET","auth":"none","permission":null,"description":"Read the current signup and season state."},{"path":"/api/v2/seasons/signup","method":"POST","auth":"session","permission":"account:read","description":"Sign up to receive a new player kingdom when the season starts."},{"path":"/api/v2/seasons/signup","method":"DELETE","auth":"session","permission":"account:read","description":"Leave the signup roster before the season starts."},{"path":"/api/v2/seasons/bets","method":"GET","auth":"session","permission":"account:read","description":"Read fake-coin alliance betting options, balance, and your current bet."},{"path":"/api/v2/seasons/bets","method":"POST","auth":"session","permission":"account:read","description":"Place or replace one fake-coin alliance bet during betting phase.","example":{"allianceId":"base-0","amount":100}},{"path":"/api/v2/admin/seasons/signups/open","method":"POST","auth":"session","permission":"roles:manage","description":"Open signups for a new season."},{"path":"/api/v2/admin/seasons/betting/open","method":"POST","auth":"session","permission":"roles:manage","description":"Close signups and open spectator alliance betting."},{"path":"/api/v2/admin/seasons/signups","method":"GET","auth":"session","permission":"accounts:list","description":"List the current season signups."},{"path":"/api/v2/admin/seasons/start","method":"POST","auth":"session","permission":"roles:manage","description":"Close signups, create player kingdoms, and start the turn clock."},{"path":"/api/v2/admin/developer/sync-roles","method":"POST","auth":"session","permission":"developer","description":"Repair developer roles from Developer badges."},{"path":"/api/v2/admin/developer/prune-sessions","method":"POST","auth":"session","permission":"developer","description":"Delete expired account sessions."},{"path":"/api/v2/admin/developer/repair-user-stats","method":"POST","auth":"session","permission":"developer","description":"Create missing user statistics rows."},{"path":"/api/v2/admin/developer/gamejolt-trophies","method":"GET/PATCH","auth":"session","permission":"developer","description":"Read or update badge-to-Game-Jolt trophy ID mappings."},{"path":"/api/v2/admin/developer/gamejolt-trophies/discover","method":"GET","auth":"session","permission":"developer","description":"Fetch Game Jolt trophy titles and IDs for automatic badge mapping."},{"path":"/api/v2/admin/developer/gamejolt-trophies/auto-sync","method":"POST","auth":"session","permission":"developer","description":"Auto-match Game Jolt trophies to badge names and save the mappings."},{"path":"/api/v2/admin/developer/restore-system-awards","method":"POST","auth":"session","permission":"developer","description":"Restore built-in badge and achievement definitions."},{"path":"/api/v2/player/join","method":"POST","auth":"session","permission":"account:read","description":"Website alias for season signup; no API key is required."},{"path":"/api/v2/player/session","method":"GET","auth":"session","permission":"account:read","description":"Read website-player signup, kingdom, and turn status."},{"path":"/api/v2/player/observation","method":"GET","auth":"session","permission":"account:read","description":"Read the signed-in player's kingdom."},{"path":"/api/v2/player/command","method":"POST","auth":"session","permission":"account:read","description":"Submit the player's single action for the current game day.","example":{"action":"recruit"}},{"path":"/api/v2/player/release","method":"POST","auth":"session","permission":"account:read","description":"Return the added player kingdom to autonomous control."},{"path":"/api/v2/register","method":"POST","auth":"session or API key","permission":"ai:join","description":"Register an external AI controller.","example":{"name":"Strategist Prime"}},{"path":"/api/v2/session","method":"GET","auth":"controller token","permission":null,"description":"Read external controller state."},{"path":"/api/v2/observation","method":"GET","auth":"controller token","permission":null,"description":"Read AI-ready game observation."},{"path":"/api/v2/command","method":"POST","auth":"controller token","permission":null,"description":"Queue an external controller action.","example":{"action":"attack","targetId":123}},{"path":"/api/v2/usage","method":"GET","auth":"session or API key","permission":"account:read","description":"Read API usage totals, errors, latency, routes, and API keys."},{"path":"/api/v2/admin/usage","method":"GET","auth":"session","permission":"accounts:list","description":"Read server-wide API usage metrics."}]}