components:
  securitySchemes:
    Bearer:
      in: header
      name: Authorization
      type: apiKey
info:
  contact:
    email: support@mythic-beasts.com
  description: '

    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](auth).


    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.


    '
  termsOfService: https://www.mythic-beasts.com/article/terms
  title: Physical Server Control API
  version: 0.0.1
openapi: 3.0.0
paths:
  /{server_type}/servers:
    get:
      description: Lists all servers associated with this account.
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  description: Server information (key will match `asset_id` property)
                  properties:
                    asset_id:
                      description: Asset ID of server (will match key)
                      type: string
                    identifier:
                      description: 'Server identifier (the service identifier without
                        a

                        prefix &mdash; see ["Identifiers"](#sec-identifiers))

                        '
                      type: string
                    name:
                      description: Friendly name for server
                      type: string
                    period:
                      description: Billing period
                      type: string
                    product:
                      description: Product code
                      type: string
                  type: object
                example:
                  B0000abcd:
                    asset_id: B0000abcd
                    identifier: dedi1
                    name: null
                    period: year
                    product: DSY1000
                  B0000bcde:
                    asset_id: B0000bcde
                    identifier: dedi2
                    name: database-server
                    period: month
                    product: DSM2000
                type: object
          description: '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.


            '
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access this API.
      security:
      - Bearer: []
      summary: List servers
      tags:
      - VPS
  /{server_type}/servers/{identifier}:
    get:
      description: '

        Returns information about the specified server.


        '
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: '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)

          '
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  asset_id:
                    description: Asset ID of server
                    example: B0000abcd
                    type: string
                  identifier:
                    description: 'Server identifier (the service identifier without
                      a

                      prefix &mdash; see ["Identifiers"](#sec-identifiers))

                      '
                    example: dedi1
                    type: string
                  ipv4:
                    description: List of IPv4 addresses of server
                    example:
                    - 46.235.224.236
                    type: array
                  ipv6:
                    description: List of IPv6 addresses of server
                    example:
                    - 2a00:1098:abcd::1
                    - 2a00:1098:abcd::2
                    type: array
                  location:
                    properties:
                      rack:
                        description: Rack in which server is located
                        example: cam-8
                        type: string
                      site:
                        description: Site (datacentre) in which server is hosted
                        example: cam
                        type: string
                    type: object
                  period:
                    description: Billing period
                    enum:
                    - year
                    - quarter
                    - month
                    example: year
                    type: string
                  price:
                    description: Price (in pence per period)
                    type: integer
                  product:
                    description: Product code
                    example: DSY1000
                    type: string
          description: Server information
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      security:
      - Bearer: []
      summary: Server information
      tags:
      - Physical
  /{server_type}/servers/{identifier}/console:
    get:
      description: Get serial console status
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: The server identifier or asset ID
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  baudrate:
                    description: Baud rate (if supported)
                    example: 115200
                    type: integer
                  cd:
                    description: CD serial line state (if supported)
                    example: false
                    type: boolean
                  cts:
                    description: CTS serial line state (if supported)
                    example: false
                    type: boolean
                  dsr:
                    description: DSR serial line state (if supported)
                    example: true
                    type: boolean
                  dtr:
                    description: DTR serial line state (if supported)
                    example: true
                    type: boolean
                  has_state:
                    description: 'Whether the console has a state websocket

                      (will be `true` for physical serial ports, `false` for

                      IPMI SOL ports)

                      '
                    example: true
                    type: boolean
                  ri:
                    description: RI serial line state (if supported)
                    example: false
                    type: boolean
                  rts:
                    description: RTS serial line state (if supported)
                    example: false
                    type: boolean
                  supports_baudrate:
                    description: 'Whether the console supports reading and setting
                      baud

                      rate (will be `true` for physical serial ports, `false` for

                      IPMI SOL ports)

                      '
                    example: true
                    type: boolean
                  supports_breaks:
                    description: 'Whether the console supports sending breaks (will

                      always be `true` for physical servers)

                      '
                    example: true
                    type: boolean
                  supports_line_state:
                    description: 'Whether the console supports reading serial line
                      state

                      (will be `true` for physical serial ports, `false` for IPMI
                      SOL

                      ports)

                      '
                    example: true
                    type: boolean
          description: Serial console status and capabilities
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      summary: Console status
      tags:
      - Physical
    put:
      description: Set serial console parameters.
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: The server identifier or asset ID
        in: path
        name: identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                baudrate:
                  description: Baud rate
                  enum:
                  - 9600
                  - 19200
                  - 38400
                  - 57600
                  - 115200
                  example: 9600
                  required: true
                  type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Response message
                    example: Settings updated
                    type: string
                type: object
          description: Parameters updated successfully
        '400':
          content:
            application/json:
              schema:
                properties:
                  message:
                    error:
                      example: 'Invalid parameter baudrate: must be one of 9600, 19200,
                        38400, 57600, 115200'
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      summary: Configure console
      tags:
      - Physical
  /{server_type}/servers/{identifier}/console/break:
    put:
      description: Send break on serial console.
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: The server identifier or asset ID
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Response message
                    example: Break sent
                    type: string
                type: object
          description: Break sent successfully
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      summary: Send break
      tags:
      - Physical
  /{server_type}/servers/{identifier}/console/log:
    get:
      description: Get serial console output
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: The server identifier or asset ID
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - default: 100
        description: Line limit (maximum number of lines of output to return; maximum
          1000)
        example: 200
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - default: true
        description: Whether or not to include timestamps in the console output
        example: false
        in: query
        name: timestamps
        required: false
        schema:
          type: boolean
      - default: true
        description: Whether or not to include state change lines in the console output
        example: false
        in: query
        name: state_changes
        required: false
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  console_output:
                    description: Console output
                    example: "2025-02-08 13:37:00: Debian GNU/Linux 10 dedi1.example.com\
                      \ ttyS0\r2025-02-08 13:37:00: dedi1 login: "
                    type: string
                  limit:
                    description: Line limit
                    example: 2
                    type: integer
          description: Console output (as a single string)
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Invalid limit (must be numeric)
                    type: string
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      summary: Console output
      tags:
      - Physical
  /{server_type}/servers/{identifier}/console/websocket:
    get:
      description: 'Returns a URL of a websocket attached to the serial console of
        the

        server.

        '
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: The server identifier or asset ID
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - default: serial
        description: 'Websocket type (plain serial data, serial data wrapped in Telnet,

          or serial state updates); check the

          [status endpoint](#ep-get-servertypeserversidentifierconsole) to

          see whether the console supports a `state` websocket

          '
        example: telnet
        in: query
        name: type
        required: false
        schema:
          enum:
          - serial
          - telnet
          - state
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  expires:
                    description: Websocket URL expiry time
                    example: '2025-03-25T14:19:51'
                    type: string
                  url:
                    description: Websocket URL
                    example: wss://ts-cam-x.consoles.mythic-beasts.com/?token=827d0118b624ac187f30d1ea4a0fb7557228ebe4519e21bcb858a51ab9d7dfc7
                    type: string
          description: Websocket URL
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      summary: Serial console websocket
      tags:
      - Physical
  /{server_type}/servers/{identifier}/power:
    get:
      description: List power connections and their state
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: The server identifier or asset ID
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  description: Power port information (key will match `index` property)
                  properties:
                    index:
                      description: Power port index (usually `0` or `1`, but may potentially
                        be an arbitrary string; will match key)
                      type: string
                    state:
                      description: Power port state
                      enum:
                      - 'on'
                      - 'off'
                      - unknown
                      type: string
                  type: object
                example:
                  0:
                    index: '0'
                    state: 'on'
                  1:
                    index: '1'
                    state: 'off'
                type: object
          description: Power ports and state
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      summary: Power ports and state
      tags:
      - Physical
  /{server_type}/servers/{identifier}/power/{power_port}:
    put:
      description: Power server (or individual power port) on or off
      parameters:
      - description: Server type
        in: path
        name: server_type
        required: true
        schema:
          enum:
          - dedicated
          - colo
          type: string
      - description: The server identifier or asset ID
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - description: 'Power port index from [power port list endpoint](#ep-get-servertypeserversidentifierpower)

          (if unspecified, controls all power ports)

          '
        in: path
        name: power_port
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                power:
                  description: Power state
                  enum:
                  - 'on'
                  - 'off'
                  - cycle
                  example: cycle
                  required: true
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Response message
                    example: Server powered on
                    type: string
                type: object
          description: Power control successful
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Invalid power port 'foo'
                    type: string
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: A description of the error
                    example: Not authorised
                    type: string
                type: object
          description: Not authorised to access server or server does not exist
      summary: Power on/off
      tags:
      - Physical
servers:
- url: https://api.mythic-beasts.com/beta
tags:
- description: Physical server control
  name: Physical
