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 '
{
  "cycle": "MONTHLY",
  "services": [
    {
      "type": "baremetal",
      "offeringId": "<plan-id>",
      "datacenterId": "<datacenter-id>"
    }
  ]
}
'

cycle takes HOURLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY or ANNUALLY, and an order without it is placed as HOURLY. What comes next depends on which you chose:

• A term (MONTHLY to ANNUALLY): the order is saved with an invoice and nothing is provisioned yet. Keep data.order.id and data.invoiceId for the next step.
• HOURLY: the server is provisioned within the request and no invoice is raised. data.provisionedItems[0].provisionedId is the server's id, the {serviceId} of the last two steps, so skip to choosing an operating system. Hourly billing needs the organization's billing.usage_based entitlement, which for now is granted on request through support in the cloud console; without it the order answers 422 USAGE_BILLING_DISABLED.

The server gets an IPv4 /30 and an IPv6 /120, both included in the plan's price. Billing covers a larger IPv4 prefix and leaving a family out.

The Idempotency-Key header is optional. Generate one value per order and send the same value again if you retry after a timeout, so the retry returns the first order instead of placing a second one; Idempotency has the rules.

Pay the invoice

A server on a term is provisioned once its invoice is paid in full, and nothing pays an order's invoice automatically. An order left unpaid is cancelled within 24 hours. From a script, Pay invoice settles it from account credit:

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

Keep providerType=ACCOUNT_CREDIT in the query: a pay request without it starts a card payment that a browser has to confirm. The payment takes what the credit balance holds, up to the amount due, and reads status SUCCEEDED. A short balance leaves part of the invoice due and the server waits for the rest; get the invoice and read amountDue. With no credit at all the call answers 422 PAYMENT_FAILED. To pay by card instead, open the invoice in the cloud console; Billing explains why a key cannot.

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 order reads UNPAID until provisioning has run. The item's provisionedId is the new server's id, the {serviceId} every later call takes. An item that reads FAILED will not come up by itself: the order reads FAILED as well, and support needs the order's id to finish it.

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 409 and the code OPERATION_IN_PROGRESS.