Quickstart

Create an API key

In the cloud console, open your organization's settings and choose Create an API Key under Manage API Keys. The console shows the key once, when it is created, so copy it before closing the dialog.

Every request in the docs shows it as <api-key> in the X-API-KEY header. Put your key in its place, and the ids each step returns in place of the other <...> values and {serviceId}.

Pick a plan and a datacenter

List the bare metal plans:

curl --request GET \
  --url https://api.serverside.com/v1/services/baremetal/plans \
  --header 'X-API-KEY: <api-key>'

Every plan in data carries its id, its hardware under specs, a price per billing cycle under pricing.rates, and availability: one entry per datacenter with that datacenter's id, its name and the quantity in stock. Choose a plan and a datacenter whose quantity is above zero, and keep both ids.

Order the server

Create an order for the plan in that datacenter, on the billing cycle you will pay by:

curl --request POST \
  --url https://api.serverside.com/v1/billing/orders \
  --header 'X-API-KEY: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "services": [
    {
      "type": "baremetal",
      "offeringId": "<plan-id>",
      "datacenterId": "<datacenter-id>"
    }
  ],
  "cycle": "MONTHLY"
}
'

cycle takes MONTHLY, QUARTERLY, SEMI_ANNUALLY or ANNUALLY. Keep two ids from the response: the order's own, data.order.id, and data.invoiceId, the invoice raised for it.

The Idempotency-Key header is optional. Generate one value per order and send the same value again if you retry after a timeout; Idempotency lists the other operations that accept it.

A server comes with an IPv4 /30 and an IPv6 /64 (Networking describes both). Adding ipv4PrefixLength to the item asks for a larger IPv4 prefix. The order then carries the IP block plan of that size as well, billed on the same cycle as a second line of the invoice.

An organization with hourly billing skips the order and the invoice. Create bare metal service takes the same two ids and answers with the new service, whose id is the {serviceId} of the last two steps:

curl --request POST \
  --url https://api.serverside.com/v1/services/baremetal \
  --header 'X-API-KEY: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offeringId": "<plan-id>",
  "datacenterId": "<datacenter-id>"
}
'

Hourly billing is the billing.usage_based entitlement, which a new organization does not have. Without it this call answers 422 with the code USAGE_BILLING_DISABLED. Get entitlements shows whether yours has it, and Apply for Hourly Billing in the cloud console asks for it.

Pay the invoice

The server is provisioned once its invoice is paid in full. From a script, Pay invoice settles it from account credit:

curl --request POST \
  --url 'https://api.serverside.com/v1/billing/invoices/{invoiceId}/pay?provider_type=ACCOUNT_CREDIT' \
  --header 'X-API-KEY: <api-key>'

A payment status of SUCCEEDED means the invoice is paid. To pay by card instead, open the invoice in the cloud console. A key cannot read the organization's saved cards, and a card that asks for 3-D Secure has to be confirmed in a browser; Billing explains both.

Then get the order every 20 seconds or so until its item in items reads status COMPLETED:

curl --request GET \
  --url https://api.serverside.com/v1/billing/orders/{orderId} \
  --header 'X-API-KEY: <api-key>'

The item's provisionedId is the new server's id, the {serviceId} every later call takes.

Choose an operating system

List the images that fit the new server:

curl --request GET \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/operations/deploy/os \
  --header 'X-API-KEY: <api-key>'

Each image has an id, a name, a platform (LINUX or WINDOWS), the defaultUser it creates and the raidVariants it supports.

Deploy it

Start the deployment. sshKeyIds takes ids from List SSH keys. On Linux, username and password are optional and apply alongside the keys, and a user named there gets passwordless sudo.

curl --request POST \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/operations/deploy \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operatingSystemId": "<image-id>",
  "sshKeyIds": [
    "<ssh-key-id>"
  ],
  "raidVariant": "RAID1"
}
'

The answer is the operation that is now running, of type DEPLOYMENT. Get the service status to follow it: operation holds the running deployment with its progress and lastProgressMessage, and lastOperation.state reads COMPLETED or FAILED once it ends. A deployment only starts while the service's state is ACTIVE; with another operation still running, the API answers 422 and the code ENTITY_STATE_INVALID.