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 hostbackend.scplist.kris for this website only, and other clients may be blocked there. - Every endpoint below is a
GETrequest 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-Agentthat names your project.
Endpoints
| Endpoint | Returns | Limit |
|---|---|---|
/api/v2/servers | The 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,2 | Current 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-count | The 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
| Field | Meaning |
|---|---|
serverId | The server's number. It stays the same when the name, IP address or port changes. |
ip, port | The address. ip is null once the server has been offline for more than 30 days. |
online | Whether the server is in the list right now. |
players | Current and maximum players as text, such as 18/30. |
version | The game version. |
friendlyFire, whitelist, modded | Flags the server reports about itself. |
isoCode | The country where the server is hosted. |
info | The server name as sanitized HTML. |
techList | Mod loaders named in the server name, with their versions. |
pastebin | The Pastebin ID of the server's info page. |
official | 0 for a community server, higher for an official one. |
distance | Estimated distance from the caller in kilometres. |
lastSeen | When 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.