What the Servers API does
The Servers API lists connected and pending server setups, creates a new setup, renames a connected server, and removes either kind. It is the developer twin of the dashboard server list, so an external setup tool can complete the same work without opening the panel.
A common read-only use is a status board or uptime monitor. A setup tool can also create a pending server, put it in a category, copy compatible settings from another server, and use the returned server id in the recorder configuration.
Authentication and scope
Authenticate with a developer API key as a bearer token. Send your key in the Authorization header on every request.
Listing requires servers:read. Creating, renaming and removing require servers:write. Mint a key with the scopes it needs from Settings, then Developer API in your dashboard. Keys are tenant-scoped, so a key only ever sees or changes servers on its own account.
A management key is bound to the member who created it. ReplayCore checks that member's current role, instance-settings permission and category or server access on every write. A caller cannot supply a different actor header. Removing or demoting the member therefore removes or reduces the key's management access.
curl https://api.replaycore.com/v1/api/servers \
-H "Authorization: Bearer rc_live_your_key_here"List response
The response is a JSON object with a servers array. Each entry carries the server's id and display name, its current status, the time it was last seen, the recorder version it is running, and how many replays it has uploaded.
status is online when the server has checked in within the last 15 minutes, and offline otherwise. lastSeenAt is null until the server connects for the first time. This is the same heartbeat signal the dashboard's Test Connection button uses, now reachable from your own code.
{
"servers": [
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Hub",
"status": "online",
"lastSeenAt": "2026-06-25T08:00:00Z",
"pluginVersion": "1.0.0",
"replayCount": 42
}
]
}Create and rename
POST /v1/api/servers with a name creates a pending setup and returns 201 with serverId and the cleaned name. Optional categoryId places it in a category; optional sourceServerId copies compatible setup from a server the member can manage. The pending setup reserves a plan slot until the recorder connects or the setup is cancelled. The pending list returns sourceServerId to workspace owners, so a setup tool can recover a create request after a lost response without creating another server identity.
PATCH /v1/api/servers/{id} with a name renames a connected server and returns the updated record. Names must contain 1 to 64 characters and cannot contain control characters.
curl -X POST https://api.replaycore.com/v1/api/servers \
-H "Authorization: Bearer rc_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"name":"BedWars EU"}'Remove or cancel
DELETE /v1/api/servers/{id} deauthorises a connected server. DELETE /v1/api/servers/permanent/{id} permanently removes its server record. DELETE /v1/api/servers/pending/{id} cancels a setup that has not connected and immediately releases its reserved plan slot. Successful deletes return 204 No Content.
A key created before member binding was introduced can still use read and integration routes, but management writes return 403 ACTOR_BINDING_REQUIRED. Replace that key through the dashboard. Other write failures distinguish a missing scope, a lost instance-settings permission, restricted access to the target, and a full plan server limit.