API / Method reference / Managing a server

Managing a server

State, power, console, players, startup, access.

Base URL:https://sourhost.net/api/v1·Auth: Authorization: Bearer sh_live_…

GET/projects/:id/services/:serviceId/stats

State and load

Scope: servers:read

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl "https://sourhost.net/api/v1/projects/12/services/34/stats" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

HTTP

HTTP/2 200 OK
{
  "powerState": "running",
  "cpuPercent": 37.5,
  "memoryBytes": 2147483648,
  "diskBytes": 8589934592,
  "uptimeMs": 5400000
}

POST/projects/:id/services/:serviceId/power

Start, stop, restart

Scope: servers:power

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)
`signal`required	body · string	start, stop, restart or kill

Example request

curl -X POST "https://sourhost.net/api/v1/projects/12/services/34/power" \
  -H "Authorization: Bearer $SOURHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signal":"restart"}'

Response

204 Empty response

POST/projects/:id/services/:serviceId/command

Console command

Scope: servers:console

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)
`command`required	body · string	One line, up to 512 characters

Example request

curl -X POST "https://sourhost.net/api/v1/projects/12/services/34/command" \
  -H "Authorization: Bearer $SOURHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"changelevel de_dust2"}'

Response

204 Empty response

Method errors

409	`server_offline`	The server isn't running
400	`command_invalid`	Empty, multi-line or over 512

GET/projects/:id/services/:serviceId/console/log

Console log

Scope: servers:console

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)
`lines`	query · number	How many of the last lines, 1–500 (default 100)

Example request

curl "https://sourhost.net/api/v1/projects/12/services/34/console/log?lines=50" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

HTTP

HTTP/2 200 OK
{
  "lines": [
    "Server is hibernating",
    "Player alice connected",
    "changelevel de_dust2"
  ]
}

GET/projects/:id/services/:serviceId/players

Players online

The same query a server browser makes. Cached for 10 seconds.

Scope: servers:read

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl "https://sourhost.net/api/v1/projects/12/services/34/players" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

HTTP

HTTP/2 200 OK
{
  "info": {
    "name": "Retake #1",
    "map": "de_dust2",
    "players": 2,
    "maxPlayers": 16,
    "bots": 0,
    "password": false,
    "vac": true,
    "version": "1.40.0.0"
  },
  "players": [
    {
      "name": "alice",
      "score": 12,
      "durationSeconds": 1830
    }
  ],
  "pingMs": 14
}

Method errors

409 server_offline The server isn't running

GET/projects/:id/services/:serviceId/variables

Startup parameters

Scope: servers:read

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl "https://sourhost.net/api/v1/projects/12/services/34/variables" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

204 Empty response

PATCH/projects/:id/services/:serviceId/variables

Change startup parameters

Applied on the next start.

Scope: servers:manage

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl -X PATCH "https://sourhost.net/api/v1/projects/12/services/34/variables" \
  -H "Authorization: Bearer $SOURHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"MAXPLAYERS":"24","MAP":"de_mirage"}}'

Response

204 Empty response

PATCH/projects/:id/services/:serviceId

Rename

Scope: servers:manage

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl -X PATCH "https://sourhost.net/api/v1/projects/12/services/34" \
  -H "Authorization: Bearer $SOURHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Retake #2"}'

Response

204 Empty response

POST/projects/:id/services/:serviceId/port

Change the port

Only on a server with its own dedicated IP.

Scope: servers:manage

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl -X POST "https://sourhost.net/api/v1/projects/12/services/34/port" \
  -H "Authorization: Bearer $SOURHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port":27016}'

Response

204 Empty response

POST/projects/:id/services/:serviceId/reinstall

Reinstall

Deletes all of the server's files and installs the game again.

Scope: servers:manage

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl -X POST "https://sourhost.net/api/v1/projects/12/services/34/reinstall" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

204 Empty response

GET/projects/:id/services/:serviceId/console

Console connection

The node console's websocket address and a token for it (~10 minutes).

Scope: servers:console

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl "https://sourhost.net/api/v1/projects/12/services/34/console" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

HTTP

HTTP/2 200 OK
{
  "token": "eyJ0eXAiOiJKV1Qi…",
  "socket": "wss://de-n3.sourhost.net:8080/api/servers/1a2b3c4d/ws"
}

GET/projects/:id/services/:serviceId/sftp

SFTP details

Scope: servers:access

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl "https://sourhost.net/api/v1/projects/12/services/34/sftp" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

HTTP

HTTP/2 200 OK
{
  "host": "de-n3.sourhost.net",
  "port": 2022,
  "username": "you.1a2b3c4d",
  "access": true
}

GET/projects/:id/services/:serviceId/access

Who has access

Scope: servers:read

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl "https://sourhost.net/api/v1/projects/12/services/34/access" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

204 Empty response

POST/projects/:id/services/:serviceId/access

Give access

Scope: servers:access

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)

Example request

curl -X POST "https://sourhost.net/api/v1/projects/12/services/34/access" \
  -H "Authorization: Bearer $SOURHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Response

204 Empty response

DELETE/projects/:id/services/:serviceId/access/:memberId

Take access away

Scope: servers:access

Parameters

`id`required	path · string	Project number (from GET /projects), or ticket number
`serviceId`required	path · string	Service number (from GET /projects/:id/services)
`memberId`required	path · string	Member ID (from the list)

Example request

curl -X DELETE "https://sourhost.net/api/v1/projects/12/services/34/access/9" \
  -H "Authorization: Bearer $SOURHOST_TOKEN"

Response

204 Empty response

Common errors

Any method can answer with these. More on errors

400	`bad_request`	Invalid body or parameters
401	`token_invalid`	The token is wrong, revoked or expired
403	`token_scope_missing`	The token lacks the scope
403	`token_project_forbidden`	The project or service is outside the token’s limits
404	`not_found`	No such project, service or object
429	`token_rate_limited`	Too many requests, see Retry-After
503	`upstream_unavailable`	The panel or node didn't answer — retry later