Read-only JSON API

codservers API

The CoDServers.net API exposes the same live masterlist used by the website for CoD1, United Offensive, CoD2 and CoD4. It is versioned, CORS-enabled and safe to call from browser apps.

Base URL

Endpoints

Query Parameters

Server list endpoints support filters and pagination.

Parameter	Example	Description
`search`	`?search=promod`	Search hostname, map, IP, country, gametype, mod, version and player names.
`country`	`?country=de`	Filter by two-letter country code.
`gametype`	`?gametype=sd`	Filter by game mode.
`version`	`?version=1.3`	Filter by version prefix.
`populated`	`?populated=1`	Only return servers reporting clients in the latest query.
`empty`	`?empty=1`	Only return servers reporting no clients in the latest query.
`passworded`	`?passworded=0`	Use `1` for locked servers or `0` for open servers.
`modded`	`?modded=1`	Only return servers with a mod or fs_game value.
`sort`	`?sort=players`	Sort by players, hostname, map, country, response_time or last_updated.
`order`	`?order=asc`	Sort direction.
`limit` / `offset`	`?limit=50&offset=50`	Paginate large result sets.

Examples

const res = await fetch('https://api.codservers.net/v1/servers/cod2?populated=1');
const json = await res.json();
console.log(json.data);

import requests

res = requests.get('https://api.codservers.net/v1/servers/cod2?populated=1')
data = res.json()
print(data['data'])

curl https://api.codservers.net/v1/summary

Response Shape

Successful responses use {"success":true,"data":...}. Errors use a structured code and message.

json

{
  "success": false,
  "error": {
    "code": "server_not_found",
    "message": "Server was not found."
  }
}

CORS is enabled with Access-Control-Allow-Origin: *. The default rate limit is 120 requests per minute per client IP. Cache headers are intentionally short because server data refreshes frequently.

Query data

Field	Meaning
`players_count`	The authoritative public population: the queried roster minus population identified as bot or synthetic with high confidence. Used for server-list counts, sorting, totals, `/top` and the populated/empty filters. Always between `0` and the number of rows in `players`.
`players`	The complete sanitized query roster used by server details, containing only `name`, `score`, and `ping`. Rows excluded from `players_count` are still listed here, so `players.length` is larger than `players_count` on servers running bots. That difference is expected, not an error.
`players_stale`	`true` when `players` is the last successfully queried detail roster after repeated status timeouts. It never contributes to `players_count`.
`last_player_at`	UTC timestamp of the most recent observation in which this server had at least one counted player, or `null` if none has been observed. Populated servers report a timestamp from the latest sweep.
`players_observed_at`	UTC observation time for the published detail roster, or `null` when no roster has been observed.
`maxplayers`	Maximum clients reported by the queried game server.
`raw_info`	Cvars returned by the server's `getinfo` response on detail and raw endpoints.
`raw_status`	Cvars returned by the server's `getstatus` response on detail and raw endpoints.

The website and public API use the same bot-filtered server-list count while retaining the complete sanitized roster for server details. Private per-player confidence, evidence, and classification reasons are not included in API responses.

Use Terms

Please cache responsibly, link back to CoDServers.net when possible, and avoid aggressive scraping. The API is free and read-only, and it does not require authentication for public use.