Physical Server Control API

OpenAPI YAML

This API enables access to consoles and power control of dedicated and colo servers hosted on Mythic Beasts infrastructure.

All requests need to be authenticated using a Bearer token obtained from our auth service.

The base URL for this service is:

  • https://api.mythic-beasts.com/beta

The endpoints listed below should be appended to the above URL.

Identifiers

Physical servers are uniquely identified by an asset ID. This is a nine-character string of the form Bxxxxxxxx where x is a digit, a lower-case letter, @, or *. Every physical server is also associated with a service identifier, which identifies the billing record for the service. The service identifier consists of a prefix (either dedicated: or colo:) and a server identifier. The server identifier is a lower case alphanumeric (plus -) string.

Endpoints

get /{server_type}/servers

https://api.mythic-beasts.com/beta/{server_type}/servers

Lists all servers associated with this account.

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo

Responses

CodeDescription
200

Server information

An object with keys giving the asset IDs of servers associated with this account. Values are objects with additional information about the server.

application/json

NameDescription
* object

Server information (key will match asset_id property)
identifier string

Server identifier (the service identifier without a prefix — see "Identifiers")
product string

Product code
period string

Billing period
name string

Friendly name for server
asset_id string

Asset ID of server (will match key)
Example
{
    "B0000abcd": {
        "identifier": "dedi1",
        "product": "DSY1000",
        "period": "year",
        "name": null,
        "asset_id": "B0000abcd"
    },
    "B0000bcde": {
        "identifier": "dedi2",
        "product": "DSM2000",
        "period": "month",
        "name": "database-server",
        "asset_id": "B0000bcde"
    }
}
403

Not authorised to access this API.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

get /{server_type}/servers/{identifier}

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}

Returns information about the specified server.

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID (if the value is nine characters long and starts with B, it will be treated as an asset ID; otherwise, it will be treated as a server identifier)

Responses

CodeDescription
200

Server information

application/json

NameDescription
product string

Product code
identifier string

Server identifier (the service identifier without a prefix — see "Identifiers")
asset_id string

Asset ID of server
period string

Billing period

Possible values:
  • year
  • quarter
  • month
price integer

Price (in pence per period)
ipv6 array

List of IPv6 addresses of server
ipv4 array

List of IPv4 addresses of server
location object
site string

Site (datacentre) in which server is hosted
rack string

Rack in which server is located
Example
{
    "product": "DSY1000",
    "identifier": "dedi1",
    "asset_id": "B0000abcd",
    "period": "year",
    "ipv6": [
        "2a00:1098:abcd::1",
        "2a00:1098:abcd::2"
    ],
    "ipv4": [
        "46.235.224.236"
    ],
    "location": {
        "site": "cam",
        "rack": "cam-8"
    }
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

get /{server_type}/servers/{identifier}/power

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}/power

List power connections and their state

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID

Responses

CodeDescription
200

Power ports and state

application/json

NameDescription
* object

Power port information (key will match index property)
index string

Power port index (usually 0 or 1, but may potentially be an arbitrary string; will match key)
state string

Power port state

Possible values:
  • on
  • off
  • unknown
Example
{
    "0": {
        "index": "0",
        "state": "on"
    },
    "1": {
        "index": "1",
        "state": "off"
    }
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

put /{server_type}/servers/{identifier}/power/{power_port}

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}/power/{power_port}

Power server (or individual power port) on or off

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID
power_port string path (Optional)

Power port index from power port list endpoint (if unspecified, controls all power ports)

Request Body JSON

NameDescription
power string

(Required) Power state

Possible values:
  • on
  • off
  • cycle
Example

application/json

{
    "power": "cycle"
}

Responses

CodeDescription
200

Power control successful

application/json

NameDescription
message string

Response message
Example
{
    "message": "Server powered on"
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Invalid power port 'foo'"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

get /{server_type}/servers/{identifier}/console/log

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}/console/log

Get serial console output

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID
limit integer query (Optional)

Line limit (maximum number of lines of output to return; maximum 1000)

Default: 100
timestamps boolean query (Optional)

Whether or not to include timestamps in the console output

Default: True
state_changes boolean query (Optional)

Whether or not to include state change lines in the console output

Default: True

Responses

CodeDescription
200

Console output (as a single string)

application/json

NameDescription
console_output string

Console output
limit integer

Line limit
Example
{
    "console_output": "2025-02-08 13:37:00: Debian GNU/Linux 10 dedi1.example.com ttyS0\r2025-02-08 13:37:00: dedi1 login: ",
    "limit": 2
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Invalid limit (must be numeric)"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

get /{server_type}/servers/{identifier}/console/websocket

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}/console/websocket

Returns a URL of a websocket attached to the serial console of the server.

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID
type query (Optional)

Websocket type (plain serial data, serial data wrapped in Telnet, or serial state updates); check the status endpoint to see whether the console supports a state websocket

Possible values:
  • serial
  • telnet
  • state
Default: serial

Responses

CodeDescription
200

Websocket URL

application/json

NameDescription
url string

Websocket URL
expires string

Websocket URL expiry time
Example
{
    "url": "wss://ts-cam-x.consoles.mythic-beasts.com/?token=827d0118b624ac187f30d1ea4a0fb7557228ebe4519e21bcb858a51ab9d7dfc7",
    "expires": "2025-03-25T14:19:51"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

put /{server_type}/servers/{identifier}/console/break

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}/console/break

Send break on serial console.

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID

Responses

CodeDescription
200

Break sent successfully

application/json

NameDescription
message string

Response message
Example
{
    "message": "Break sent"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

get /{server_type}/servers/{identifier}/console

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}/console

Get serial console status

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID

Responses

CodeDescription
200

Serial console status and capabilities

application/json

NameDescription
has_state boolean

Whether the console has a state websocket (will be true for physical serial ports, false for IPMI SOL ports)
supports_baudrate boolean

Whether the console supports reading and setting baud rate (will be true for physical serial ports, false for IPMI SOL ports)
supports_breaks boolean

Whether the console supports sending breaks (will always be true for physical servers)
supports_line_state boolean

Whether the console supports reading serial line state (will be true for physical serial ports, false for IPMI SOL ports)
baudrate integer

Baud rate (if supported)
rts boolean

RTS serial line state (if supported)
cts boolean

CTS serial line state (if supported)
dtr boolean

DTR serial line state (if supported)
dsr boolean

DSR serial line state (if supported)
ri boolean

RI serial line state (if supported)
cd boolean

CD serial line state (if supported)
Example
{
    "has_state": true,
    "supports_baudrate": true,
    "supports_breaks": true,
    "supports_line_state": true,
    "baudrate": 115200,
    "rts": false,
    "cts": false,
    "dtr": true,
    "dsr": true,
    "ri": false,
    "cd": false
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

put /{server_type}/servers/{identifier}/console

https://api.mythic-beasts.com/beta/{server_type}/servers/{identifier}/console

Set serial console parameters.

Parameters

NameLocationDescription
server_type string path

Server type

Possible values:
  • dedicated
  • colo
identifier string path

The server identifier or asset ID

Request Body JSON

NameDescription
baudrate integer

(Required) Baud rate

Possible values:
  • 9600
  • 19200
  • 38400
  • 57600
  • 115200
Example

application/json

{
    "baudrate": 9600
}

Responses

CodeDescription
200

Parameters updated successfully

application/json

NameDescription
message string

Response message
Example
{
    "message": "Settings updated"
}
400

Bad request

application/json

NameDescription
message
Example
{}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

Support Index

Page contents