{
  "openapi" : "3.1.0",
  "info" : {
    "title" : "Whiteout Survival Atlas API",
    "summary" : "Read the census: players, alliances, rosters and rankings.",
    "description" : "A read-only census API over the Whiteout Survival world map. Authenticate with a developer API key, issued from https://wosatlas.com/developers. Every response carries the two quota header triples and the burst triple; branch a retry on the `error` code and `Retry-After`, never on a remaining counter.",
    "version" : "1",
    "termsOfService" : "https://wosatlas.com/developers/terms",
    "contact" : {
      "name" : "Whiteout Survival Atlas",
      "url" : "https://wosatlas.com/support"
    },
    "license" : {
      "name" : "Whiteout Survival Atlas API Terms",
      "url" : "https://wosatlas.com/developers/terms"
    }
  },
  "servers" : [
    {
      "url" : "https://api.wosatlas.com",
      "description" : "Production"
    }
  ],
  "x-retry-policy" : "Take the retry decision from the `error` code and the `Retry-After` header, never from a remaining counter. A monthly denial and a daily-search denial are both 429 and both leave the OTHER window's remaining counter truthfully non-zero, so a client watching only `X-Quota-Remaining` will see a 429 beside a large remaining count and conclude the server is broken.",
  "x-quota-windows" : "Both quota windows are ROLLING, not calendar periods: the read window looks back thirty days from now and the search window looks back twenty-four hours from now. Quota and search windows are metered per ACCOUNT, not per key — every key an account holds draws on one budget.",
  "x-error-codes" : {
    "INVALID_API_KEY" : {
      "status" : 401,
      "description" : "The key is unknown, revoked, or its owning account has been deleted."
    },
    "ENDPOINT_NOT_ALLOWED" : {
      "status" : 403,
      "description" : "The route is not on the developer surface. Presenting a key on a route off the surface is refused rather than served, so do not send a key to endpoints this document does not list."
    },
    "QUOTA_EXCEEDED" : {
      "status" : 429,
      "description" : "The account's rolling thirty-day read quota is spent. `X-Quota-Remaining` reads zero; `X-Search-Remaining` stays honest."
    },
    "SEARCH_QUOTA_EXCEEDED" : {
      "status" : 429,
      "description" : "The account's rolling twenty-four-hour search quota is spent. `X-Search-Remaining` reads zero; `X-Quota-Remaining` stays honest. Only the two search routes count against it."
    },
    "RATE_LIMIT_EXCEEDED" : {
      "status" : 429,
      "description" : "The account's short burst window is full. `X-RateLimit-Remaining` reads zero. This is a per-second-scale ceiling and clears on its own; neither quota window has been touched."
    }
  },
  "security" : [
    {
      "ApiKeyAuth" : [ ]
    },
    {
      "BearerAuth" : [ ]
    }
  ],
  "paths" : {
    "/v1/alliances/leaderboard" : {
      "get" : {
        "operationId" : "allianceLeaderboard",
        "summary" : "Rank alliances by total power",
        "description" : "An hourly roll-up ranking alliances by total power, globally or within one State. Counts and totals only; it names no member.",
        "x-cost-class" : "STANDARD",
        "parameters" : [
          {
            "name" : "kid",
            "in" : "query",
            "required" : false,
            "description" : "Rank within this State only. Omit for the global ranking.",
            "schema" : {
              "type" : "integer"
            },
            "example" : "165"
          },
          {
            "name" : "limit",
            "in" : "query",
            "required" : false,
            "description" : "How many rows to return.",
            "schema" : {
              "type" : "integer",
              "minimum" : 1,
              "maximum" : 200
            },
            "example" : "25"
          }
        ],
        "responses" : {
          "200" : {
            "description" : "The census read.",
            "headers" : {
              "X-Quota-Limit" : {
                "description" : "The account's read allowance for the rolling thirty-day window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Remaining" : {
                "description" : "Reads left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Reset" : {
                "description" : "Unix seconds at which the oldest read in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Limit" : {
                "description" : "The account's search allowance for the rolling twenty-four-hour window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Remaining" : {
                "description" : "Searches left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Reset" : {
                "description" : "Unix seconds at which the oldest search in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Limit" : {
                "description" : "The account's burst allowance for the short window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Remaining" : {
                "description" : "Requests left in the burst window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Reset" : {
                "description" : "Unix seconds at which the burst window rolls.",
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "entries" : {
                      "type" : "array",
                      "items" : {
                        "type" : "object",
                        "properties" : {
                          "abbr" : {
                            "type" : "string"
                          },
                          "aid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "joinMinLevel" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "joinMinPower" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "kid" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "kingdomName" : {
                            "type" : "string"
                          },
                          "maxPower" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "medianPower" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "memberMax" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "members" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "name" : {
                            "type" : "string"
                          },
                          "publicRecruit" : {
                            "type" : "boolean"
                          },
                          "recordSource" : {
                            "type" : "string",
                            "enum" : [
                              "SERVER",
                              "DERIVED"
                            ]
                          },
                          "recordedAt" : {
                            "type" : "string",
                            "format" : "date-time"
                          },
                          "totalPower" : {
                            "type" : "integer",
                            "format" : "int64"
                          }
                        },
                        "required" : [
                          "abbr",
                          "aid",
                          "joinMinLevel",
                          "joinMinPower",
                          "kid",
                          "kingdomName",
                          "maxPower",
                          "medianPower",
                          "memberMax",
                          "members",
                          "name",
                          "publicRecruit",
                          "recordSource",
                          "recordedAt",
                          "totalPower"
                        ],
                        "additionalProperties" : false
                      }
                    },
                    "kid" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "recordedAt" : {
                      "type" : "string",
                      "format" : "date-time"
                    }
                  },
                  "required" : [
                    "entries",
                    "kid",
                    "recordedAt"
                  ],
                  "additionalProperties" : false
                }
              }
            },
            "x-redacted" : false
          },
          "401" : {
            "$ref" : "#/components/responses/Unauthorized"
          },
          "403" : {
            "$ref" : "#/components/responses/Forbidden"
          },
          "429" : {
            "$ref" : "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/v1/alliances/recruiting" : {
      "get" : {
        "operationId" : "allianceRecruiting",
        "summary" : "List alliances taking applications",
        "description" : "Alliances open to applications that still have a seat free, filtered by State, language and joining requirements.",
        "x-cost-class" : "STANDARD",
        "parameters" : [
          {
            "name" : "kid",
            "in" : "query",
            "required" : false,
            "description" : "Restrict to one State.",
            "schema" : {
              "type" : "integer",
              "minimum" : 1
            },
            "example" : "165"
          },
          {
            "name" : "language",
            "in" : "query",
            "required" : false,
            "description" : "The alliance's declared language, in the game's own vocabulary.",
            "schema" : {
              "type" : "integer",
              "minimum" : 1,
              "maximum" : 21
            },
            "example" : "1"
          },
          {
            "name" : "minLevel",
            "in" : "query",
            "required" : false,
            "description" : "Exclude alliances whose joining level requirement is above this.",
            "schema" : {
              "type" : "integer",
              "minimum" : 1,
              "maximum" : 99
            },
            "example" : "25"
          },
          {
            "name" : "minPower",
            "in" : "query",
            "required" : false,
            "description" : "Exclude alliances whose joining power requirement is above this.",
            "schema" : {
              "type" : "integer",
              "minimum" : 0
            },
            "example" : "1000000"
          },
          {
            "name" : "powerMin",
            "in" : "query",
            "required" : false,
            "description" : "Only alliances whose own total power is at least this.",
            "schema" : {
              "type" : "integer",
              "minimum" : 0
            },
            "example" : "1000000"
          },
          {
            "name" : "powerMax",
            "in" : "query",
            "required" : false,
            "description" : "Only alliances whose own total power is at most this.",
            "schema" : {
              "type" : "integer",
              "minimum" : 0
            },
            "example" : "9000000000"
          },
          {
            "name" : "limit",
            "in" : "query",
            "required" : false,
            "description" : "Page size.",
            "schema" : {
              "type" : "integer",
              "minimum" : 1,
              "maximum" : 200
            },
            "example" : "25"
          },
          {
            "name" : "offset",
            "in" : "query",
            "required" : false,
            "description" : "How many rows to skip.",
            "schema" : {
              "type" : "integer",
              "minimum" : 0
            },
            "example" : "0"
          }
        ],
        "responses" : {
          "200" : {
            "description" : "The census read.",
            "headers" : {
              "X-Quota-Limit" : {
                "description" : "The account's read allowance for the rolling thirty-day window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Remaining" : {
                "description" : "Reads left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Reset" : {
                "description" : "Unix seconds at which the oldest read in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Limit" : {
                "description" : "The account's search allowance for the rolling twenty-four-hour window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Remaining" : {
                "description" : "Searches left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Reset" : {
                "description" : "Unix seconds at which the oldest search in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Limit" : {
                "description" : "The account's burst allowance for the short window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Remaining" : {
                "description" : "Requests left in the burst window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Reset" : {
                "description" : "Unix seconds at which the burst window rolls.",
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "entries" : {
                      "type" : "array",
                      "items" : {
                        "type" : "object",
                        "properties" : {
                          "abbr" : {
                            "type" : "string"
                          },
                          "aid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "joinMinLevel" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "joinMinPower" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "kid" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "kingdomName" : {
                            "type" : "string"
                          },
                          "language" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "memberMax" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "members" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "name" : {
                            "type" : "string"
                          },
                          "power" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "powerReadAt" : {
                            "type" : "string",
                            "format" : "date-time"
                          },
                          "publicRecruit" : {
                            "type" : "boolean"
                          },
                          "recordReadAt" : {
                            "type" : "string",
                            "format" : "date-time"
                          },
                          "recordSource" : {
                            "type" : "string",
                            "enum" : [
                              "SERVER",
                              "DERIVED"
                            ]
                          }
                        },
                        "required" : [
                          "abbr",
                          "aid",
                          "joinMinLevel",
                          "joinMinPower",
                          "kid",
                          "kingdomName",
                          "language",
                          "memberMax",
                          "members",
                          "name",
                          "power",
                          "powerReadAt",
                          "publicRecruit",
                          "recordReadAt",
                          "recordSource"
                        ],
                        "additionalProperties" : false
                      }
                    },
                    "limit" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "offset" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "recordsReadAt" : {
                      "type" : "string",
                      "format" : "date-time"
                    },
                    "total" : {
                      "type" : "integer",
                      "format" : "int32"
                    }
                  },
                  "required" : [
                    "entries",
                    "limit",
                    "offset",
                    "recordsReadAt",
                    "total"
                  ],
                  "additionalProperties" : false
                }
              }
            },
            "x-redacted" : false
          },
          "401" : {
            "$ref" : "#/components/responses/Unauthorized"
          },
          "403" : {
            "$ref" : "#/components/responses/Forbidden"
          },
          "429" : {
            "$ref" : "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/v1/alliances/search" : {
      "get" : {
        "operationId" : "searchAlliances",
        "summary" : "Search alliances by tag or name",
        "description" : "Free-text search over alliance tags and names, with a per-State member breakdown on each hit. Counts against the search window.",
        "x-cost-class" : "SEARCH",
        "parameters" : [
          {
            "name" : "tag",
            "in" : "query",
            "required" : true,
            "description" : "An alliance tag or name fragment.",
            "schema" : {
              "type" : "string"
            },
            "example" : "EVL"
          },
          {
            "name" : "kingdomIds",
            "in" : "query",
            "required" : false,
            "description" : "Restrict the search to these State ids.",
            "schema" : {
              "type" : "array",
              "items" : {
                "type" : "integer"
              }
            },
            "example" : "165"
          }
        ],
        "responses" : {
          "200" : {
            "description" : "The census read.",
            "headers" : {
              "X-Quota-Limit" : {
                "description" : "The account's read allowance for the rolling thirty-day window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Remaining" : {
                "description" : "Reads left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Reset" : {
                "description" : "Unix seconds at which the oldest read in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Limit" : {
                "description" : "The account's search allowance for the rolling twenty-four-hour window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Remaining" : {
                "description" : "Searches left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Reset" : {
                "description" : "Unix seconds at which the oldest search in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Limit" : {
                "description" : "The account's burst allowance for the short window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Remaining" : {
                "description" : "Requests left in the burst window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Reset" : {
                "description" : "Unix seconds at which the burst window rolls.",
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "alliances" : {
                      "type" : "array",
                      "items" : {
                        "type" : "object",
                        "properties" : {
                          "abbr" : {
                            "type" : "string"
                          },
                          "aid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "homeKid" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "homeKingdomName" : {
                            "type" : "string"
                          },
                          "kingdoms" : {
                            "type" : "array",
                            "items" : {
                              "type" : "object",
                              "properties" : {
                                "kid" : {
                                  "type" : "integer",
                                  "format" : "int32"
                                },
                                "kingdomName" : {
                                  "type" : "string"
                                },
                                "memberCount" : {
                                  "type" : "integer",
                                  "format" : "int32"
                                }
                              },
                              "required" : [
                                "kid",
                                "kingdomName",
                                "memberCount"
                              ],
                              "additionalProperties" : false
                            }
                          },
                          "totalMembers" : {
                            "type" : "integer",
                            "format" : "int64"
                          }
                        },
                        "required" : [
                          "abbr",
                          "aid",
                          "homeKid",
                          "homeKingdomName",
                          "kingdoms",
                          "totalMembers"
                        ],
                        "additionalProperties" : false
                      }
                    },
                    "viewerTier" : {
                      "type" : "string",
                      "enum" : [
                        "ANONYMOUS",
                        "FREE",
                        "PASS",
                        "DEVELOPER"
                      ]
                    }
                  },
                  "required" : [
                    "alliances",
                    "viewerTier"
                  ],
                  "additionalProperties" : false
                }
              }
            },
            "x-redacted" : true
          },
          "401" : {
            "$ref" : "#/components/responses/Unauthorized"
          },
          "403" : {
            "$ref" : "#/components/responses/Forbidden"
          },
          "429" : {
            "$ref" : "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/v1/alliances/{aid}/members" : {
      "get" : {
        "operationId" : "getAllianceMembers",
        "summary" : "Fetch one alliance and its roster",
        "description" : "The alliance record and every member the atlas has mapped to it. A keyed read, not a scan.",
        "x-cost-class" : "STANDARD",
        "parameters" : [
          {
            "name" : "aid",
            "in" : "path",
            "required" : true,
            "description" : "The alliance id.",
            "schema" : {
              "type" : "integer"
            },
            "example" : "1000015"
          }
        ],
        "responses" : {
          "200" : {
            "description" : "The census read.",
            "headers" : {
              "X-Quota-Limit" : {
                "description" : "The account's read allowance for the rolling thirty-day window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Remaining" : {
                "description" : "Reads left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Reset" : {
                "description" : "Unix seconds at which the oldest read in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Limit" : {
                "description" : "The account's search allowance for the rolling twenty-four-hour window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Remaining" : {
                "description" : "Searches left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Reset" : {
                "description" : "Unix seconds at which the oldest search in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Limit" : {
                "description" : "The account's burst allowance for the short window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Remaining" : {
                "description" : "Requests left in the burst window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Reset" : {
                "description" : "Unix seconds at which the burst window rolls.",
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "abbr" : {
                      "type" : "string"
                    },
                    "aid" : {
                      "type" : "integer",
                      "format" : "int64"
                    },
                    "derivedMemberCount" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "derivedRecordedAt" : {
                      "type" : "string",
                      "format" : "date-time"
                    },
                    "derivedTotalPower" : {
                      "type" : "integer",
                      "format" : "int64"
                    },
                    "homeKid" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "honorLevel" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "joinMinLevel" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "joinMinPower" : {
                      "type" : "integer",
                      "format" : "int64"
                    },
                    "language" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "leaderName" : {
                      "type" : "string"
                    },
                    "leaderUid" : {
                      "type" : "integer",
                      "format" : "int64"
                    },
                    "lv" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "manifesto" : {
                      "type" : "string"
                    },
                    "memberCount" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "memberMax" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "members" : {
                      "type" : "array",
                      "items" : {
                        "type" : "object",
                        "properties" : {
                          "abbr" : {
                            "type" : "string"
                          },
                          "kid" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "kingdom_name" : {
                            "type" : "string"
                          },
                          "lv" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "nick_name" : {
                            "type" : "string"
                          },
                          "office" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "uid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "x" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "y" : {
                            "type" : "integer",
                            "format" : "int32"
                          }
                        },
                        "required" : [
                          "abbr",
                          "kid",
                          "kingdom_name",
                          "lv",
                          "nick_name",
                          "office",
                          "uid",
                          "x",
                          "y"
                        ],
                        "additionalProperties" : false
                      }
                    },
                    "name" : {
                      "type" : "string"
                    },
                    "notice" : {
                      "type" : "string"
                    },
                    "noticePresent" : {
                      "type" : "boolean"
                    },
                    "noticeTime" : {
                      "type" : "string",
                      "format" : "date-time"
                    },
                    "powerRank" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "publicRecruit" : {
                      "type" : "boolean"
                    },
                    "rankedAlliances" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "recordMissingSince" : {
                      "type" : "string",
                      "format" : "date-time"
                    },
                    "recordReadAt" : {
                      "type" : "string",
                      "format" : "date-time"
                    },
                    "recordSource" : {
                      "type" : "string",
                      "enum" : [
                        "SERVER",
                        "DERIVED"
                      ]
                    },
                    "serverPower" : {
                      "type" : "integer",
                      "format" : "int64"
                    },
                    "serverPowerRank" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "viewerTier" : {
                      "type" : "string",
                      "enum" : [
                        "ANONYMOUS",
                        "FREE",
                        "PASS",
                        "DEVELOPER"
                      ]
                    }
                  },
                  "required" : [
                    "abbr",
                    "aid",
                    "derivedMemberCount",
                    "derivedRecordedAt",
                    "derivedTotalPower",
                    "homeKid",
                    "honorLevel",
                    "joinMinLevel",
                    "joinMinPower",
                    "language",
                    "leaderName",
                    "leaderUid",
                    "lv",
                    "manifesto",
                    "memberCount",
                    "memberMax",
                    "members",
                    "name",
                    "notice",
                    "noticePresent",
                    "noticeTime",
                    "powerRank",
                    "publicRecruit",
                    "rankedAlliances",
                    "recordMissingSince",
                    "recordReadAt",
                    "recordSource",
                    "serverPower",
                    "serverPowerRank",
                    "viewerTier"
                  ],
                  "additionalProperties" : false
                }
              }
            },
            "x-redacted" : true
          },
          "401" : {
            "$ref" : "#/components/responses/Unauthorized"
          },
          "403" : {
            "$ref" : "#/components/responses/Forbidden"
          },
          "429" : {
            "$ref" : "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/v1/players/search" : {
      "get" : {
        "operationId" : "searchPlayers",
        "summary" : "Search players by name or Chief ID",
        "description" : "Free-text search over player names, with exact Chief ID and internal uid matches merged in front of the name page. Counts against the search window.",
        "x-cost-class" : "SEARCH",
        "parameters" : [
          {
            "name" : "playerName",
            "in" : "query",
            "required" : true,
            "description" : "A name fragment, a Chief ID, or an internal uid.",
            "schema" : {
              "type" : "string"
            },
            "example" : "LordFrost"
          },
          {
            "name" : "kingdomIds",
            "in" : "query",
            "required" : false,
            "description" : "Restrict the search to these State ids. Repeat or comma-separate.",
            "schema" : {
              "type" : "array",
              "items" : {
                "type" : "integer"
              }
            },
            "example" : "165"
          }
        ],
        "responses" : {
          "200" : {
            "description" : "The census read.",
            "headers" : {
              "X-Quota-Limit" : {
                "description" : "The account's read allowance for the rolling thirty-day window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Remaining" : {
                "description" : "Reads left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Reset" : {
                "description" : "Unix seconds at which the oldest read in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Limit" : {
                "description" : "The account's search allowance for the rolling twenty-four-hour window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Remaining" : {
                "description" : "Searches left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Reset" : {
                "description" : "Unix seconds at which the oldest search in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Limit" : {
                "description" : "The account's burst allowance for the short window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Remaining" : {
                "description" : "Requests left in the burst window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Reset" : {
                "description" : "Unix seconds at which the burst window rolls.",
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "idOutcome" : {
                      "type" : "string",
                      "enum" : [
                        "MATCHED",
                        "UNMATCHED_INCOMPLETE",
                        "UNMATCHED_COMPLETE",
                        "NOT_AN_ID"
                      ]
                    },
                    "players" : {
                      "type" : "array",
                      "items" : {
                        "type" : "object",
                        "properties" : {
                          "abbr" : {
                            "type" : "string"
                          },
                          "aid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "current_power" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "fid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "furnace_lv" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "kid" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "kingdom_name" : {
                            "type" : "string"
                          },
                          "last_jump_pct" : {
                            "type" : "number"
                          },
                          "lv" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "nick_name" : {
                            "type" : "string"
                          },
                          "observed_at" : {
                            "type" : "string",
                            "format" : "date-time"
                          },
                          "stove_lv" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "uid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "x" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "y" : {
                            "type" : "integer",
                            "format" : "int32"
                          }
                        },
                        "required" : [
                          "abbr",
                          "aid",
                          "current_power",
                          "fid",
                          "furnace_lv",
                          "kid",
                          "kingdom_name",
                          "last_jump_pct",
                          "lv",
                          "nick_name",
                          "observed_at",
                          "stove_lv",
                          "uid",
                          "x",
                          "y"
                        ],
                        "additionalProperties" : false
                      }
                    },
                    "stateKid" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "viewerTier" : {
                      "type" : "string",
                      "enum" : [
                        "ANONYMOUS",
                        "FREE",
                        "PASS",
                        "DEVELOPER"
                      ]
                    }
                  },
                  "required" : [
                    "idOutcome",
                    "players",
                    "stateKid",
                    "viewerTier"
                  ],
                  "additionalProperties" : false
                }
              }
            },
            "x-redacted" : true
          },
          "401" : {
            "$ref" : "#/components/responses/Unauthorized"
          },
          "403" : {
            "$ref" : "#/components/responses/Forbidden"
          },
          "429" : {
            "$ref" : "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/v1/players/{uid}" : {
      "get" : {
        "operationId" : "getPlayer",
        "summary" : "Fetch one player by internal uid",
        "description" : "The current snapshot for one player, keyed on the atlas's own uid rather than the Chief ID a player sees.",
        "x-cost-class" : "STANDARD",
        "parameters" : [
          {
            "name" : "uid",
            "in" : "path",
            "required" : true,
            "description" : "The atlas's internal player id, as returned by the search routes.",
            "schema" : {
              "type" : "integer"
            },
            "example" : "400001"
          }
        ],
        "responses" : {
          "200" : {
            "description" : "The census read.",
            "headers" : {
              "X-Quota-Limit" : {
                "description" : "The account's read allowance for the rolling thirty-day window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Remaining" : {
                "description" : "Reads left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Quota-Reset" : {
                "description" : "Unix seconds at which the oldest read in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Limit" : {
                "description" : "The account's search allowance for the rolling twenty-four-hour window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Remaining" : {
                "description" : "Searches left in that window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-Search-Reset" : {
                "description" : "Unix seconds at which the oldest search in the window ages out.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Limit" : {
                "description" : "The account's burst allowance for the short window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Remaining" : {
                "description" : "Requests left in the burst window.",
                "schema" : {
                  "type" : "string"
                }
              },
              "X-RateLimit-Reset" : {
                "description" : "Unix seconds at which the burst window rolls.",
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "idOutcome" : {
                      "type" : "string",
                      "enum" : [
                        "MATCHED",
                        "UNMATCHED_INCOMPLETE",
                        "UNMATCHED_COMPLETE",
                        "NOT_AN_ID"
                      ]
                    },
                    "players" : {
                      "type" : "array",
                      "items" : {
                        "type" : "object",
                        "properties" : {
                          "abbr" : {
                            "type" : "string"
                          },
                          "aid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "current_power" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "fid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "furnace_lv" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "kid" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "kingdom_name" : {
                            "type" : "string"
                          },
                          "last_jump_pct" : {
                            "type" : "number"
                          },
                          "lv" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "nick_name" : {
                            "type" : "string"
                          },
                          "observed_at" : {
                            "type" : "string",
                            "format" : "date-time"
                          },
                          "stove_lv" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "uid" : {
                            "type" : "integer",
                            "format" : "int64"
                          },
                          "x" : {
                            "type" : "integer",
                            "format" : "int32"
                          },
                          "y" : {
                            "type" : "integer",
                            "format" : "int32"
                          }
                        },
                        "required" : [
                          "abbr",
                          "aid",
                          "current_power",
                          "fid",
                          "furnace_lv",
                          "kid",
                          "kingdom_name",
                          "last_jump_pct",
                          "lv",
                          "nick_name",
                          "observed_at",
                          "stove_lv",
                          "uid",
                          "x",
                          "y"
                        ],
                        "additionalProperties" : false
                      }
                    },
                    "stateKid" : {
                      "type" : "integer",
                      "format" : "int32"
                    },
                    "viewerTier" : {
                      "type" : "string",
                      "enum" : [
                        "ANONYMOUS",
                        "FREE",
                        "PASS",
                        "DEVELOPER"
                      ]
                    }
                  },
                  "required" : [
                    "idOutcome",
                    "players",
                    "stateKid",
                    "viewerTier"
                  ],
                  "additionalProperties" : false
                }
              }
            },
            "x-redacted" : true
          },
          "401" : {
            "$ref" : "#/components/responses/Unauthorized"
          },
          "403" : {
            "$ref" : "#/components/responses/Forbidden"
          },
          "429" : {
            "$ref" : "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "components" : {
    "securitySchemes" : {
      "ApiKeyAuth" : {
        "type" : "apiKey",
        "in" : "header",
        "name" : "X-Api-Key",
        "description" : "The raw key, exactly as it was shown once at creation. Begins `wos_`."
      },
      "BearerAuth" : {
        "type" : "http",
        "scheme" : "bearer",
        "description" : "The same key presented as `Authorization: Bearer wos_...`."
      }
    },
    "schemas" : {
      "ErrorResponse" : {
        "type" : "object",
        "properties" : {
          "details" : {
            "type" : "object",
            "additionalProperties" : true
          },
          "error" : {
            "type" : "string"
          },
          "message" : {
            "type" : "string"
          },
          "retryAfter" : {
            "type" : "string",
            "format" : "date-time"
          },
          "timestamp" : {
            "type" : "string",
            "format" : "date-time"
          }
        },
        "required" : [
          "details",
          "error",
          "message",
          "retryAfter",
          "timestamp"
        ],
        "additionalProperties" : false
      }
    },
    "responses" : {
      "Unauthorized" : {
        "description" : "INVALID_API_KEY — The key is unknown, revoked, or its owning account has been deleted.",
        "headers" : {
          "X-Quota-Limit" : {
            "description" : "The account's read allowance for the rolling thirty-day window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Quota-Remaining" : {
            "description" : "Reads left in that window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Quota-Reset" : {
            "description" : "Unix seconds at which the oldest read in the window ages out.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Limit" : {
            "description" : "The account's search allowance for the rolling twenty-four-hour window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Remaining" : {
            "description" : "Searches left in that window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Reset" : {
            "description" : "Unix seconds at which the oldest search in the window ages out.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Limit" : {
            "description" : "The account's burst allowance for the short window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Remaining" : {
            "description" : "Requests left in the burst window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Reset" : {
            "description" : "Unix seconds at which the burst window rolls.",
            "schema" : {
              "type" : "string"
            }
          }
        },
        "x-error-codes" : [
          "INVALID_API_KEY"
        ],
        "content" : {
          "application/json" : {
            "schema" : {
              "$ref" : "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden" : {
        "description" : "ENDPOINT_NOT_ALLOWED — The route is not on the developer surface. Presenting a key on a route off the surface is refused rather than served, so do not send a key to endpoints this document does not list.",
        "headers" : {
          "X-Quota-Limit" : {
            "description" : "The account's read allowance for the rolling thirty-day window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Quota-Remaining" : {
            "description" : "Reads left in that window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Quota-Reset" : {
            "description" : "Unix seconds at which the oldest read in the window ages out.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Limit" : {
            "description" : "The account's search allowance for the rolling twenty-four-hour window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Remaining" : {
            "description" : "Searches left in that window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Reset" : {
            "description" : "Unix seconds at which the oldest search in the window ages out.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Limit" : {
            "description" : "The account's burst allowance for the short window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Remaining" : {
            "description" : "Requests left in the burst window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Reset" : {
            "description" : "Unix seconds at which the burst window rolls.",
            "schema" : {
              "type" : "string"
            }
          }
        },
        "x-error-codes" : [
          "ENDPOINT_NOT_ALLOWED"
        ],
        "content" : {
          "application/json" : {
            "schema" : {
              "$ref" : "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "TooManyRequests" : {
        "description" : "QUOTA_EXCEEDED — The account's rolling thirty-day read quota is spent. `X-Quota-Remaining` reads zero; `X-Search-Remaining` stays honest. SEARCH_QUOTA_EXCEEDED — The account's rolling twenty-four-hour search quota is spent. `X-Search-Remaining` reads zero; `X-Quota-Remaining` stays honest. Only the two search routes count against it. RATE_LIMIT_EXCEEDED — The account's short burst window is full. `X-RateLimit-Remaining` reads zero. This is a per-second-scale ceiling and clears on its own; neither quota window has been touched.",
        "headers" : {
          "X-Quota-Limit" : {
            "description" : "The account's read allowance for the rolling thirty-day window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Quota-Remaining" : {
            "description" : "Reads left in that window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Quota-Reset" : {
            "description" : "Unix seconds at which the oldest read in the window ages out.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Limit" : {
            "description" : "The account's search allowance for the rolling twenty-four-hour window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Remaining" : {
            "description" : "Searches left in that window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-Search-Reset" : {
            "description" : "Unix seconds at which the oldest search in the window ages out.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Limit" : {
            "description" : "The account's burst allowance for the short window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Remaining" : {
            "description" : "Requests left in the burst window.",
            "schema" : {
              "type" : "string"
            }
          },
          "X-RateLimit-Reset" : {
            "description" : "Unix seconds at which the burst window rolls.",
            "schema" : {
              "type" : "string"
            }
          },
          "Retry-After" : {
            "description" : "Seconds to wait before retrying. Sent on every 429, and specific to the window that denied.",
            "schema" : {
              "type" : "string"
            }
          }
        },
        "x-error-codes" : [
          "QUOTA_EXCEEDED",
          "SEARCH_QUOTA_EXCEEDED",
          "RATE_LIMIT_EXCEEDED"
        ],
        "content" : {
          "application/json" : {
            "schema" : {
              "$ref" : "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}