show

Devices

Device Management. Check out the product docs to learn more about Server Devices.

Retrieve BGP neighbor data for this device

GET
/devices/{id}/bgp/neighbors

Provides a summary of the BGP neighbor data associated to the BGP sessions for this device.

Retrieve all BGP sessions

GET
/devices/{id}/bgp/sessions

Provides a listing of available BGP sessions for the device.

Create a BGP session

POST
/devices/{id}/bgp/sessions

Creates a BGP session.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    bgp_session
     (required) in body

    BGP session to create

    {
    "address_family": "string",
    "default_route": "boolean"
}

Retrieve device's events

GET
/devices/{id}/events

Returns a list of events pertaining to a specific device

  • Parameters
  • id
    string  (required) in path

    Device UUID

    include
    array in query

    Nested attributes to include. Included objects will return their full attributes. Attribute names can be dotted (up to 3 levels) to included deeply nested objects.

    exclude
    array in query

    Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

    page
    integer in query  (minimum: 1)  (maximum: 100000)

    Page to return

    Default: 1

    per_page
    integer in query  (minimum: 1)  (maximum: 1000)

    Items returned per page

    Default: 10

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Perform an action

POST
/devices/{id}/actions

Performs an action for the given device. Possible actions include: power_on, power_off, reboot, reinstall, and rescue (reboot the device into rescue OS.)

  • Parameters
  • id
    string  (required) in path

    Device UUID

    type
    string  (required) in query

    Action to perform

Retrieve all devices of an organization

GET
/organizations/{id}/devices

Provides a collection of devices for a given organization.

  • Parameters
  • id
    string  (required) in path

    Organization UUID

    include
    array in query

    Nested attributes to include. Included objects will return their full attributes. Attribute names can be dotted (up to 3 levels) to included deeply nested objects.

    exclude
    array in query

    Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

    page
    integer in query  (minimum: 1)  (maximum: 100000)

    Page to return

    Default: 1

    per_page
    integer in query  (minimum: 1)  (maximum: 1000)

    Items returned per page

    Default: 10

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Retrieve all devices of a project

GET
/projects/{id}/devices

Provides a collection of devices for a given project.

  • Parameters
  • id
    string  (required) in path

    Project UUID

    include
    array in query

    Nested attributes to include. Included objects will return their full attributes. Attribute names can be dotted (up to 3 levels) to included deeply nested objects.

    exclude
    array in query

    Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

    page
    integer in query  (minimum: 1)  (maximum: 100000)

    Page to return

    Default: 1

    per_page
    integer in query  (minimum: 1)  (maximum: 1000)

    Items returned per page

    Default: 10

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Create a device

POST
/projects/{id}/devices

Creates a new device and provisions it in the specified location.

  Device type-specific options are accepted.  For example, `baremetal` devices accept `operating_system`, `hostname`, and `plan`. These parameters may not be accepted for other device types. The default device type is `baremetal`.
  • Parameters
  • id
    string  (required) in path

    Project UUID

    device
     (required) in body

    Device to create

    facility, plan, operating_system

    {
    "facility": "string",
    "plan": "string",
    "hostname": "string",
    "description": "string",
    "billing_cycle": "string",
    "operating_system": "string",
    "always_pxe": "boolean",
    "ipxe_script_url": "string",
    "userdata": "string",
    "locked": "boolean",
    "customdata": "object",
    "metro": "string",
    "hardware_reservation_id": "string",
    "spot_instance": "boolean",
    "spot_price_max": "number",
    "termination_time": "string",
    "tags": [
        "string"
    ],
    "project_ssh_keys": [
        "string"
    ],
    "user_ssh_keys": [
        "string"
    ],
    "ssh_keys": [
        {
            "label": "string",
            "key": "string"
        }
    ],
    "no_ssh_keys": "boolean",
    "features": [
        "string"
    ],
    "public_ipv4_subnet_size": "number",
    "private_ipv4_subnet_size": "number",
    "ip_addresses": [
        {
            "type": "object",
            "address_family": "number",
            "public": "boolean",
            "cidr": "number",
            "ip_reservations": "array"
        }
    ]
}

Retrieve a device

GET
/devices/{id}

Type-specific options (such as facility for baremetal devices) will be included as part of the main data structure. State value can be one of: active inactive queued or provisioning

  • Parameters
  • id
    string  (required) in path

    Device UUID

    include
    array in query

    Nested attributes to include. Included objects will return their full attributes. Attribute names can be dotted (up to 3 levels) to included deeply nested objects.

    exclude
    array in query

    Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Update the device

PUT
/devices/{id}

Updates the device.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    device
     (required) in body

    Facility to update

    {
    "hostname": "string",
    "description": "string",
    "billing_cycle": "string",
    "userdata": "string",
    "locked": "boolean",
    "tags": [
        "string"
    ],
    "always_pxe": "boolean",
    "ipxe_script_url": "string",
    "spot_instance": "boolean",
    "customdata": "object"
}

Delete the device

DELETE
/devices/{id}

Deletes a device and deprovisions it in our datacenter.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    force_delete
    boolean in query

    Force the deletion of the device, by detaching any storage volume still active.

Create a devices batch

POST
/projects/{id}/devices/batch

Creates new devices in batch and provisions them in our datacenter.

Type-specific options (such as operating_system for baremetal devices) should be included in the main data structure alongside hostname and plan.

The features attribute allows you to optionally specify what features your server should have.

For example, if you require a server with a TPM chip, you may specify { "features": { "tpm": "required" } } (or { "features": ["tpm"] } in shorthand).

The request will fail if there are no available servers matching your criteria. Alternatively, if you do not require a certain feature, but would prefer to be assigned a server with that feature if there are any available, you may specify that feature with a preferred value (see the example request below).

The request will not fail if we have no servers with that feature in our inventory.

The facilities attribute specifies in what datacenter you wish to create the device.

You can either specify a single facility { "facility": "f1" } , or you can instruct to create the device in the best available datacenter { "facility": "any" }. Additionally it is possible to set a prioritized location selection.

For example { "facility": ["f3", "f2", "any"] } will try to assign to the facility f3, if there are no available f2, and so on. If "any" is not specified for "facility", the request will fail unless it can assign in the selected locations.

With { "facility": "any" } you have the option to diversify to indicate how many facilities you are willing to be spread across. For this purpose use parameter: facility_diversity_level = N.

For example:

{ "facilities": ["sjc1", "ewr1", "any"] , "facility_diversity_level" = 1, "quantity" = 10 } will assign 10 devices into the same facility, trying first in "sjc1", and if there aren’t available, it will try in "ewr1", otherwise any other.

The ip_addresses attribute will allow you to specify the addresses you want created with your device.

To maintain backwards compatibility, If the attribute is not sent in the request, it will be treated as if { "ip_addresses": [{ "address_family": 4, "public": true }, { "address_family": 4, "public": false }, { "address_family": 6, "public": true }] } was sent.

The private IPv4 address is required and always need to be sent in the array. Not all operating systems support no public IPv4 address, so in those cases you will receive an error message.

For example, to only configure your server with a private IPv4 address, you can send { "ip_addresses": [{ "address_family": 4, "public": false }] }.

Note: when specifying a subnet size larger than a /30, you will need to supply the UUID(s) of existing ip_reservations in your project to assign IPs from.

For example, { "ip_addresses": [..., {"address_family": 4, "public": true, "ip_reservations": ["uuid1", "uuid2"]}] }

To access a server without public IPs, you can use our Out-of-Band console access (SOS) or use another server with public IPs as a proxy.

  • Parameters
  • id
    string  (required) in path

    Project UUID

    batch
     (required) in body

    Batches to create

    {
    "batches": [
        {
            "type": "object",
            "plan": "string",
            "hostname": "string",
            "hostnames": "array",
            "facility": "array",
            "metro": "string",
            "description": "string",
            "billing_cycle": "string",
            "operating_system": "string",
            "always_pxe": "boolean",
            "userdata": "string",
            "locked": "boolean",
            "termination_time": "string",
            "tags": "array",
            "project_ssh_keys": "array",
            "user_ssh_keys": "array",
            "no_ssh_keys": "boolean",
            "features": "array",
            "customdata": "object",
            "ip_addresses": "array"
        }
    ]
}

Retrieve an instance bandwidth

GET
/devices/{id}/bandwidth

Retrieve an instance bandwidth for a given period of time.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    from
    string  (required) in query

    Timestamp from range

    until
    string  (required) in query

    Timestamp to range

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Retrieve all ip assignments

GET
/devices/{id}/ips

Returns all ip assignments for a device.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    include
    array in query

    Nested attributes to include. Included objects will return their full attributes. Attribute names can be dotted (up to 3 levels) to included deeply nested objects.

    exclude
    array in query

    Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Create a ip assignment

POST
/devices/{id}/ips

Creates an ip assignment for a device.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    ip_assignment
     (required) in body

    IPAssignment to create

    address

    {
    "address": "string",
    "manageable": "boolean",
    "customdata": "object"
}

Retrieve the custom metadata of an instance

GET
/devices/{id}/customdata

Provides the custom metadata stored for this instance in json format

Retrieve the custom metadata of an IP Assignment

GET
/devices/{instance_id}/ips/{id}/customdata

Provides the custom metadata stored for this IP Assignment in json format

  • Parameters
  • instance_id
    string  (required) in path

    Instance UUID

    id
    string  (required) in path

    Ip Assignment UUID

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Retrieve device traffic

GET
/devices/{id}/traffic

Returns traffic for a specific device.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    direction
    string  (required) in query

    Traffic direction

    timeframe
     (required) in body

    Traffic timeframe

    started_at, ended_at

    {
    "started_at": "string",
    "ended_at": "string"
}
    interval
    string in query

    Traffic interval

    bucket
    string in query

    Traffic bucket

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Retrieve all usages for device

GET
/devices/{id}/usages

Returns all usages for a device.

  • Parameters
  • id
    string  (required) in path

    Device UUID

    created[after]
    string in query

    Filter usages created after this date

    created[before]
    string in query

    Filter usages created before this date

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Retrieve all usages for project

GET
/projects/{id}/usages

Returns all usages for a project.

  • Parameters
  • id
    string  (required) in path

    Project UUID

    created[after]
    string in query

    Filter usages created after this date

    created[before]
    string in query

    Filter usages created before this date

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide