API

A free, read-only HTTP API for the current SCP: Secret Laboratory server list. It needs no key. Player counts for Discord bots are its most common use.

Basics

  • The base address is https://api.scplist.kr. The host backend.scplist.kr is for this website only, and other clients may be blocked there.
  • Every endpoint below is a GET request that returns JSON.
  • The data is refreshed once a minute, so asking more often returns the same answer.
  • There is no key and no sign-up. Send a User-Agent that names your project.

Endpoints

EndpointReturnsLimit
/api/v2/serversThe online servers with their ID, name, current and maximum players. Filters: country, hideEmpty, hideFull, friendlyFire, whitelist, modded, minPlayers, maxPlayers, minSlots, maxSlots.10 per minute
/api/v2/servers/players?serverIds=1,2Current and maximum players of the servers you list. Offline servers are left out.20 per minute
/api/v2/servers/{serverId}One server in full: address, version, flags, country, players, name and mods.10 per minute
/api/v2/servers/online-countThe number of online servers and the players on them.30 per minute

The older POST /api/servers and GET /api/servers/{serverId} still answer, but they are deprecated and limited to 3 requests per minute.

Rate limits

Limits are counted per IP address and per endpoint. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Window-Seconds. Past the limit the API answers 429 with a Retry-After header. Responses also carry Cache-Control, and a client that honours it stays well inside the limits.

Example: a player count for a Discord bot

A server's ID is the number in the address of its page here, such as scplist.kr/servers/12345.

curl "https://api.scplist.kr/api/v2/servers/players?serverIds=12345"

[{"serverId":12345,"current":18,"max":30}]

The same request in JavaScript. Ask once a minute at most, because the data does not change faster.

const response = await fetch('https://api.scplist.kr/api/v2/servers/players?serverIds=12345');
const [server] = await response.json();
console.log(server ? `${server.current}/${server.max}` : 'offline');

Fields of a server

FieldMeaning
serverIdThe server's number. It stays the same when the name, IP address or port changes.
ip, portThe address. ip is null once the server has been offline for more than 30 days.
onlineWhether the server is in the list right now.
playersCurrent and maximum players as text, such as 18/30.
versionThe game version.
friendlyFire, whitelist, moddedFlags the server reports about itself.
isoCodeThe country where the server is hosted.
infoThe server name as sanitized HTML.
techListMod loaders named in the server name, with their versions.
pastebinThe Pastebin ID of the server's info page.
official0 for a community server, higher for an official one.
distanceEstimated distance from the caller in kilometres.
lastSeenWhen an offline server was last online. Null for an online server.

Fair use

  • Use only the endpoints on this page. Others can change without notice.
  • Traffic that ignores the limits may be blocked.
  • For higher limits or a question about the API, email support@scplist.kr.

Live reference

The reference below is generated from the running API, and you can try requests from this page.