{"openapi":"3.1.0","info":{"title":"VoxelRank API","version":"1.0.0","description":"Votes, stats and listing data from VoxelRank.\n\n**Keys.** Every listing has an API key on its dashboard. Send it as the `X-Api-Key` header (preferred), a `key` query parameter or a `key` field in a JSON body.\n\n**Test data.** The key `demo` works on every endpoint tagged Votes and returns made-up data for an example listing, so you can build and test an integration without one. Its data follows the clock (the newest votes are always a few minutes old), claiming with it changes nothing, and endpoints that act on a real listing refuse it with 403.\n\n**Limits.** 120 requests a minute per key; without a valid key (and with the demo key) 120 a minute per IP. Over that, 429 with a Retry-After header. `/servers` without a key is also limited to 30 requests a minute and the first 25 pages; send any listing's key for the full list, which is capped at 2000 requests a day per key (ask us if your integration needs more).\n\n**Times** are unix seconds; months and days are UTC."},"servers":[{"url":"https://voxelrank.com/api"}],"tags":[{"name":"Votes","description":"A listing's votes and vote stats. Needs the listing's key (or the demo key)."},{"name":"Players","description":"Per-player lookups for the in-game plugin. Needs a real key."},{"name":"Public","description":"Listing data anyone can read. No key."}],"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Your listing's key, or `demo` for test data."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"key"}},"parameters":{"key":{"name":"key","in":"query","description":"Your API key, if not sent as the X-Api-Key header.","schema":{"type":"string"},"required":false,"example":"demo"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable error code.","examples":["invalid_key"]}},"required":["error"]},"Server":{"type":"object","properties":{"id":{"type":"integer","description":"Listing id."},"name":{"type":"string","description":"Listing name."},"slug":{"type":"string","description":"URL slug, unique."},"ip":{"type":["string","null"],"description":"Java address players join with (`host` or `host:port`). null when the owner hides it."},"bedrock":{"type":["string","null"],"description":"Bedrock address, when the listing has one."},"apply_url":{"type":["string","null"],"description":"Whitelist application link, only when the address is hidden."},"version":{"type":["string","null"],"description":"Game version text as shown on the listing."},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code."},"tags":{"type":"array","items":{"type":"string"},"description":"Tag slugs."},"languages":{"type":"array","items":{"type":"string"},"description":"Language codes."},"online":{"type":"boolean","description":"Online at the last ping."},"players":{"type":["integer","null"],"description":"Players online at the last ping."},"max_players":{"type":["integer","null"],"description":"Player slots at the last ping."},"motd":{"type":["string","null"],"description":"Message of the day at the last ping."},"votes_month":{"type":"integer","description":"Votes this calendar month (UTC). Resets on the 1st; this is what the ranking uses."},"votes_total":{"type":"integer","description":"Votes ever."},"tier":{"type":"integer","description":"Premium tier, 0 for none."},"url":{"type":"string","description":"Listing page.","format":"uri"},"vote_url":{"type":"string","description":"Vote page.","format":"uri"},"banner":{"type":"string","description":"SVG banner.","format":"uri"}},"required":["id","name","slug","ip","bedrock","apply_url","version","country","tags","languages","online","players","max_players","motd","votes_month","votes_total","tier","url","vote_url","banner"]},"ServerWithRank":{"allOf":[{"$ref":"#/components/schemas/Server"},{"type":"object","properties":{"rank":{"type":"integer","description":"Position in the ranking right now."},"rating":{"type":"number","description":"Average review rating, 0 when there are none."}},"required":["rank","rating"]}]},"KeyServer":{"allOf":[{"$ref":"#/components/schemas/Server"},{"type":"object","properties":{"rank":{"type":"integer","description":"Position in the ranking right now."},"month":{"type":"string","description":"The current vote month, `YYYY-MM` (UTC)."}},"required":["rank","month"]}]},"Vote":{"type":"object","properties":{"id":{"type":"integer","description":"Vote id. Increases with every vote; use it to page and to claim."},"username":{"type":"string","description":"Player name the vote was cast for. For a vote made with \"Sign in with Steam\" this is the steamid64."},"timestamp":{"type":"integer","description":"When the vote was cast, unix seconds."},"steamid":{"type":"string","description":"Only on votes made with \"Sign in with Steam\" (Steam games): the voter's steamid64, 17 digits.","pattern":"^\\d{17}$"}},"required":["id","username","timestamp"]},"VoteWithClaim":{"allOf":[{"$ref":"#/components/schemas/Vote"},{"type":"object","properties":{"claimed":{"type":"boolean","description":"Already marked as rewarded through /v1/votes/claim."}},"required":["claimed"]}]},"VotePage":{"type":"object","properties":{"votes":{"type":"array","items":{"$ref":"#/components/schemas/VoteWithClaim"}},"next_after":{"type":["integer","null"],"description":"Pass as `after` to get the next page. null when this was the last one."}},"required":["votes","next_after"]},"VoteCheck":{"type":"object","properties":{"username":{"type":"string","description":"The name asked about, as sent. Only when asked by `username`."},"steamid":{"type":"string","description":"The steamid64 asked about. Only when asked by `steamid`."},"voted_recently":{"type":"boolean","description":"Voted in the last 24 hours."},"last_vote":{"type":["integer","null"],"description":"Last vote, unix seconds. null if never."},"total":{"type":"integer","description":"Votes ever by this player for this listing."},"month":{"type":"integer","description":"Votes this month by this player for this listing."},"status":{"type":"integer","description":"Only when asked by `steamid`. The last 24 hours: 0 = no vote, 1 = voted and not claimed yet, 2 = voted and already claimed.","enum":[0,1,2]}},"required":["voted_recently","last_vote","total","month"]},"TopVoter":{"type":"object","properties":{"username":{"type":"string","description":"Player name."},"votes":{"type":"integer","description":"Votes in the month."},"last_vote":{"type":"integer","description":"Their latest vote in the month, unix seconds."}},"required":["username","votes","last_vote"]},"Stats":{"type":"object","properties":{"month":{"type":"string","description":"The current vote month, `YYYY-MM` (UTC)."},"votes_today":{"type":"integer","description":"Votes since 00:00 UTC."},"votes_month":{"type":"integer","description":"Votes this month; the number the ranking uses."},"votes_total":{"type":"integer","description":"Votes ever."},"unique_voters_month":{"type":"integer","description":"Different player names that voted this month."},"rank":{"type":"integer","description":"Position in the ranking right now."},"daily":{"type":"array","description":"One entry per UTC day, oldest first, today last. Days without votes are included with 0.","items":{"type":"object","properties":{"date":{"type":"string","description":"UTC date, `YYYY-MM-DD`.","format":"date"},"votes":{"type":"integer","description":"Votes that day."}},"required":["date","votes"]}}},"required":["month","votes_today","votes_month","votes_total","unique_voters_month","rank","daily"]},"Claimed":{"type":"object","properties":{"claimed":{"type":"integer","description":"How many votes were unclaimed and are now claimed."},"username":{"type":"string","description":"Only for a claim by `username`: the name, as sent."},"steamid":{"type":"string","description":"Only for a claim by `steamid`: the steamid64, as sent."},"ids":{"type":"array","items":{"type":"integer"},"description":"Only for a claim by player: the vote ids claimed now."},"status":{"type":"integer","description":"Only for a claim by player. 1 = there were unclaimed votes in the last 24 hours and they are claimed now (give the reward `claimed` times), 2 = voted but already claimed, 0 = no vote in the last 24 hours.","enum":[0,1,2]}},"required":["claimed"]},"ServerList":{"type":"object","properties":{"total":{"type":"integer","description":"Listings matching the filters."},"page":{"type":"integer","description":"This page, from 1."},"pages":{"type":"integer","description":"Number of pages."},"servers":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Server"},{"type":"object","additionalProperties":true}]}}},"required":["total","page","pages","servers"]},"StatusMap":{"type":"object","description":"Keyed by listing id.","additionalProperties":{"type":"object","properties":{"online":{"type":"boolean","description":"Online at the last ping."},"players":{"type":["integer","null"],"description":"Players online."},"max":{"type":["integer","null"],"description":"Player slots."},"unreliable":{"type":"boolean","description":"The player count is known to be wrong (shared proxies); show it as unknown."},"unknown":{"type":"boolean","description":"The last check could not measure this listing (a Realm, or a game with no status query), so `online` is a default, not a measurement. Show the status as unknown."}},"required":["online","players","max","unreliable","unknown"]}},"PlayerVotes":{"type":"object","properties":{"username":{"type":"string","description":"The name asked about."},"cooldown_hours":{"type":"integer","description":"The site default cooldown. Each server has its own below."},"servers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Listing id."},"name":{"type":"string","description":"Listing name."},"slug":{"type":"string","description":"Listing slug."},"votes":{"type":"integer","description":"Votes by this player for the listing."},"last_vote":{"type":"integer","description":"Last vote, unix seconds."},"cooldown_left":{"type":"integer","description":"Seconds until the player can vote for it again, 0 or less when they can now."},"cooldown_hours":{"type":"integer","description":"This listing's cooldown."},"can_vote_now":{"type":"boolean","description":"cooldown_left <= 0."}},"required":["id","name","slug","votes","last_vote","cooldown_left","cooldown_hours","can_vote_now"]}}},"required":["username","cooldown_hours","servers"]},"Referral":{"type":"object","properties":{"username":{"type":"string","description":"Player name."},"eligible":{"type":"boolean","description":"The name interacted with your listing here recently and has not been rewarded for it."},"reason":{"type":"string","description":"Why.","enum":["bad_username","no_interaction","expired","already_claimed","no_new_interaction","ok"]},"ttl_seconds":{"type":"integer","description":"How long an interaction counts."},"disclaimer":{"type":"string","description":"What `eligible` does and does not prove."}},"required":["username","eligible","reason"],"additionalProperties":true}}},"paths":{"/v1/server":{"get":{"tags":["Votes"],"operationId":"getOwnServer","summary":"Your listing, with its rank and vote counts","parameters":[{"$ref":"#/components/parameters/key"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyServer"},"example":{"id":8685,"name":"Pear SMP","slug":"pear-smp","ip":"play.pearsmp.net","bedrock":null,"apply_url":null,"version":"1.21.4","country":"US","tags":["survival","smp"],"languages":["en"],"online":true,"players":47,"max_players":200,"motd":"Pear SMP · Season 3","votes_month":312,"votes_total":4120,"tier":0,"url":"https://voxelrank.com/server/8685-pear-smp","vote_url":"https://voxelrank.com/vote/8685-pear-smp","banner":"https://voxelrank.com/banner/pear-smp.svg","rank":12,"month":"2026-09"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/stats":{"get":{"tags":["Votes"],"operationId":"getVoteStats","summary":"Vote totals, unique voters and votes per day","parameters":[{"$ref":"#/components/parameters/key"},{"name":"days","in":"query","description":"How many days the `daily` series covers, 1 to 90. Default 30.","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"},"example":{"month":"2026-09","votes_today":18,"votes_month":312,"votes_total":4120,"unique_voters_month":64,"rank":12,"daily":[{"date":"2026-09-25","votes":24},{"date":"2026-09-26","votes":17},{"date":"2026-09-27","votes":18}]}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/top":{"get":{"tags":["Votes"],"operationId":"getTopVoters","summary":"Top voters of a month","parameters":[{"$ref":"#/components/parameters/key"},{"name":"month","in":"query","description":"Month, `YYYY-MM` (UTC). Default: this month.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"example":"2026-09"},{"name":"limit","in":"query","description":"How many, 1 to 100. Default 10.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"Most votes first; a tie goes to whoever reached it first.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TopVoter"}},"example":[{"username":"Notch","votes":27,"last_vote":1790000000},{"username":"Alex","votes":25,"last_vote":1789996400}]}}},"400":{"description":"`month` is not `YYYY-MM`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_month"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/votes":{"get":{"tags":["Votes"],"operationId":"listVotes","summary":"Every vote, oldest first, in pages","description":"For syncing votes into your own system: keep the last `next_after` you saw and ask for `after=` it next time.","parameters":[{"$ref":"#/components/parameters/key"},{"name":"after","in":"query","description":"Only votes with a larger id. Default 0 (from the start).","schema":{"type":"integer","minimum":0}},{"name":"since","in":"query","description":"Only votes cast at or after this unix time.","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","description":"Page size, 1 to 500. Default 100.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VotePage"},"example":{"votes":[{"id":2045812,"username":"Notch","timestamp":1790000000,"claimed":true},{"id":2045813,"username":"Alex","timestamp":1790000240,"claimed":false}],"next_after":null}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/votes/unclaimed":{"get":{"tags":["Votes"],"operationId":"listUnclaimedVotes","summary":"Votes not yet rewarded","description":"The reward loop: fetch these, give the rewards, then claim the ids so they are not returned again.","parameters":[{"$ref":"#/components/parameters/key"},{"name":"limit","in":"query","description":"1 to 500. Default 100.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Oldest first.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Vote"}},"example":[{"id":2045812,"username":"Notch","timestamp":1790000000},{"id":2045813,"username":"Alex","timestamp":1790000240}]}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/votes/claim":{"post":{"tags":["Votes"],"operationId":"claimVotes","summary":"Mark votes as rewarded","description":"Two ways, told apart by the body:\n\n- `ids`: the vote ids you got from /v1/votes/unclaimed. Answers `{ claimed }`.\n- `steamid` or `username` (no `ids`): every unclaimed vote of that player from the last 24 hours, claimed in one step, so two calls at once cannot both get them. `username` only matches votes made by typing a name. Answers `{ steamid | username, claimed, ids, status }`. Give the reward when `claimed` is above 0.","parameters":[{"$ref":"#/components/parameters/key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer"},"maxItems":500,"description":"Vote ids from /v1/votes/unclaimed."},"steamid":{"type":"string","description":"A player's steamid64, 17 digits (Steam games).","pattern":"^\\d{17}$"},"username":{"type":"string","description":"A player name, up to 32 characters.","maxLength":32}},"required":[]},"examples":{"ids":{"value":{"ids":[2045812,2045813]}},"steamid":{"value":{"steamid":"76561197960287930"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claimed"},"example":{"claimed":2}}}},"400":{"description":"`steamid` is not 17 digits, or `username` is too long.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_steamid"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/votes/check":{"get":{"tags":["Votes"],"operationId":"checkPlayerVote","summary":"Did a player vote?","description":"Send `username`, or `steamid` for a Steam game. The answer by `steamid` also has `status`: 0 = no vote in the last 24 hours, 1 = voted and not claimed yet, 2 = voted and already claimed.","parameters":[{"$ref":"#/components/parameters/key"},{"name":"username","in":"query","description":"Player name (case-insensitive).","schema":{"type":"string"},"example":"Notch"},{"name":"steamid","in":"query","description":"A player's steamid64, 17 digits. Used instead of `username` when sent.","schema":{"type":"string","pattern":"^\\d{17}$"},"example":"76561197960287930"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteCheck"},"example":{"username":"Notch","voted_recently":true,"last_vote":1790000000,"total":140,"month":27}}}},"400":{"description":"`steamid` is not 17 digits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_steamid"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/player/votes":{"get":{"tags":["Players"],"operationId":"getPlayerCooldowns","summary":"Which listings a player voted for, and when they can vote again","parameters":[{"$ref":"#/components/parameters/key"},{"name":"username","in":"query","description":"Player name.","schema":{"type":"string"},"required":true,"example":"Notch"},{"name":"limit","in":"query","description":"1 to 200. Default 100.","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerVotes"},"example":{"username":"Notch","cooldown_hours":24,"servers":[{"id":8685,"name":"Pear SMP","slug":"pear-smp","votes":27,"last_vote":1790000000,"cooldown_left":3600,"cooldown_hours":24,"can_vote_now":false}]}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"403":{"description":"The demo key is not accepted here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"demo_key_not_allowed"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/v1/referral/check":{"get":{"tags":["Players"],"operationId":"checkReferral","summary":"Did this player come to your server from a listing interaction?","parameters":[{"$ref":"#/components/parameters/key"},{"name":"username","in":"query","description":"Player name.","schema":{"type":"string"},"required":true,"example":"Notch"},{"name":"ip","in":"query","description":"Optional: the address the player connects from, to corroborate a join click. Never returned.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Referral"},"example":{"username":"Notch","eligible":true,"reason":"ok","source":"vote","seen_ago":3400,"expires_in":601400,"claimed_at":null,"corroborated":false,"match":"none","ttl_seconds":604800,"disclaimer":"Confirms the username interacted with your listing here, not that the player followed a link. Treat it as a welcome gift, not proof of origin."}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_key"}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/servers":{"get":{"tags":["Public"],"operationId":"listServers","summary":"Search and page through listings","security":[{},{"ApiKeyHeader":[]}],"description":"Takes the same filters as the website's own list (copy a filtered list's query string).","parameters":[{"name":"q","in":"query","description":"Text search.","schema":{"type":"string"}},{"name":"tag","in":"query","description":"Tag slug.","schema":{"type":"string"}},{"name":"version","in":"query","description":"Game version.","schema":{"type":"string"}},{"name":"sort","in":"query","description":"votes (default), players, new, rating, …","schema":{"type":"string"}},{"name":"page","in":"query","description":"Page, from 1.","schema":{"type":"integer","minimum":1}},{"name":"onlineOnly","in":"query","description":"1 for online listings only.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerList"},"example":{"total":1,"page":1,"pages":1,"servers":[{"id":8685,"name":"Pear SMP","slug":"pear-smp","ip":"play.pearsmp.net","bedrock":null,"apply_url":null,"version":"1.21.4","country":"US","tags":["survival","smp"],"languages":["en"],"online":true,"players":47,"max_players":200,"motd":"Pear SMP · Season 3","votes_month":312,"votes_total":4120,"tier":0,"url":"https://voxelrank.com/server/8685-pear-smp","vote_url":"https://voxelrank.com/vote/8685-pear-smp","banner":"https://voxelrank.com/banner/pear-smp.svg"}]}}}},"403":{"description":"Past page 25 without a key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`key_required_for_page`"},"max_page":{"type":"integer","description":"The last page available without a key."}},"required":["error","max_page"]},"example":{"error":"key_required_for_page","max_page":25}}}},"429":{"description":"More than 120 requests a minute. Wait `retry_after` seconds (also in the Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`rate_limited`"},"retry_after":{"type":"integer","description":"Seconds."}},"required":["error","retry_after"]},"example":{"error":"rate_limited","retry_after":12}}}}}}},"/server/{slug}":{"get":{"tags":["Public"],"operationId":"getServer","summary":"One listing by slug","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"pear-smp"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerWithRank"},"example":{"id":8685,"name":"Pear SMP","slug":"pear-smp","ip":"play.pearsmp.net","bedrock":null,"apply_url":null,"version":"1.21.4","country":"US","tags":["survival","smp"],"languages":["en"],"online":true,"players":47,"max_players":200,"motd":"Pear SMP · Season 3","votes_month":312,"votes_total":4120,"tier":0,"url":"https://voxelrank.com/server/8685-pear-smp","vote_url":"https://voxelrank.com/vote/8685-pear-smp","banner":"https://voxelrank.com/banner/pear-smp.svg","rank":12,"rating":4.6}}}},"404":{"description":"No such listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found"}}}}}}},"/servers/status":{"get":{"tags":["Public"],"operationId":"getServerStatus","summary":"Online state and player counts for up to 100 listings","security":[],"parameters":[{"name":"ids","in":"query","description":"Comma-separated listing ids.","schema":{"type":"string"},"required":true,"example":"8685,120"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusMap"},"example":{"8685":{"online":true,"players":47,"max":200,"unreliable":false,"unknown":false}}}}}}}}}}