API conventions

Base URL and versions

https://api.serverside.com

Every path starts with a version segment, /v1. Requests and responses are JSON over HTTPS; send Content-Type: application/json with any request that has a body. Every response carries an X-Request-Id header.

Names and values

A field with a fixed set of values lists them under Allowed values on its endpoint page. The API matches them without regard to case, so per_hour reads as PER_HOUR. A value outside the list, a number in place of the name, or a comma-separated list is refused with 400, and the error names the values the field takes.

IDs are UUIDs. IP addresses and networks travel as strings, such as "192.0.2.10" and "192.0.2.0/28". Timestamps are ISO 8601 strings, and one you send has to carry its offset: 2026-09-20T00:00:00Z and 2026-09-20T02:00:00+02:00 are read as the same instant, and 2026-09-20T00:00:00 is refused. A JSON property the endpoint does not know is ignored, so a misspelled optional field is dropped without an error.

Success and error responses

The HTTP status tells the two shapes apart: a 2xx answer is a success, anything else is an error, and success repeats that in the body.

Success

{
  "success": true,
  "data": { },
  "pagination": {
    "totalRecords": 42,
    "currentPage": 1,
    "pageSize": 25,
    "totalPages": 2
  }
}

204 No Content answers have no body at all. A 202 Accepted answer comes from a call whose change is still being applied, such as attaching a virtual network or switching boot mode, and its data holds the change's progress: a status of APPLYING and since, the time the change was accepted. Download invoice PDF is the one endpoint that returns a file instead of JSON.

Error

{
  "success": false,
  "data": null,
  "code": "VALIDATION_ERROR",
  "message": "pageSize: Must be between 1 and 1000.",
  "traceId": "SRV-7F3A-0C21-9B4E-51D2",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "Must be between 1 and 1000.",
      "field": "pageSize",
      "location": "query"
    }
  ]
}

The error body shares success and data with a success, so a client can read both with one type.

Pagination

A list whose endpoint page names page among its query parameters is paged, and all of them take the same set:

The other lists, such as List OS images and List available datacenters, return every row in data at once and carry no pagination.

To read everything from a paged list, request pages until currentPage reaches totalPages. An empty list answers with totalPages 0 and currentPage 1, so check for 0 first. A page past the end returns the last page again, so a loop that waits for an empty page never stops on a list with rows in it.

curl --request GET \
  --url 'https://api.serverside.com/v1/services/baremetal?page=2&pageSize=100&sortColumn=name' \
  --header 'X-API-KEY: <api-key>'

A filter on a text field matches any value that contains it, ignoring case. A filter on a field with allowed values takes the value as the API writes it, filter[status]=CANCELLATION_REQUESTED, and a value the field does not have is a 400 whose detail names filter[status] as the field. A filter on a true-or-false field takes true or false; any other value is ignored, so the list comes back unfiltered on that field. Fields of other types cannot be filtered.

sortColumn and the names inside filter[...] are the stored property, which is not always spelled like the JSON field, and they are not part of the stable contract. A name the endpoint does not know is ignored without an error: a mistyped filter returns the list unfiltered, and a mistyped sortColumn returns it unsorted. Without sortColumn the order is not fixed either, since invoices come back sorted by currency and subscriptions in no set order, so pages can repeat or skip rows. Send sortColumn on every list you page through.

Errors

Statuses

Retry-After is a number of seconds. Every 503 has it, and so does each 409 that clears by itself, such as a management controller that is restarting. Retrying a 500, 502 or 504 is safe for reads. Of the calls that create something, only the five listed under Idempotency take a key that makes a retry safe; before retrying any other, list what exists, since the first request may have gone through.

Validation

Two codes carry a list of details:

• VALIDATION_ERROR, 400: the request could not be read. A detail's code is INVALID_BODY when the JSON body itself cannot be read: bad syntax, a wrong type, a missing required member, a value outside a field's allowed values. It is INVALID_VALUE for a query, route or header value, and for a body field that was read but breaks a declared limit such as a length or a range. VALUE_OUT_OF_RANGE marks a number the operation checks in its own code.
• VALIDATION_FAILED, 422: the request was read, and one or more rules refused it. Each detail's code names the rule, such as BILLING_CYCLE_UNAVAILABLE on an order, and its location is null.

A body field is named by its JSON path, with indexes for arrays (services[0].offeringId, billingAddress.countryCode). A query field is named as you sent it, a route field by its parameter name and a header by its name. With one detail, message reads field: problem; with several, The request has N problems: followed by each of them.

An order on a billing cycle its plan is not sold on:

{
  "success": false,
  "data": null,
  "code": "VALIDATION_FAILED",
  "message": "cycle: This billing cycle is not offered.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B",
  "details": [
    {
      "code": "BILLING_CYCLE_UNAVAILABLE",
      "message": "This billing cycle is not offered.",
      "field": "cycle",
      "location": null
    }
  ]
}

An id in the body that matches nothing is treated by what it names. A plan, image, application or network segment id is a 422 with a detail on that field, such as OFFERING_NOT_FOUND. An id of something your organization owns (a server, a network, an SSH key) is a 404 ENTITY_NOT_FOUND with no field, so another organization's id looks the same as one that does not exist. An unknown datacenterId is 422 OFFERING_NOT_AVAILABLE.

Codes

Codes that any endpoint can answer:

Codes for bare metal servers:

Codes for orders and billing:

Networking codes are listed in Managing IP addresses and Setting up virtual networks, next to the calls that answer them. VALIDATION_FAILED detail codes are named in the guide for the operation that sends them.

Idempotency

Five operations accept an Idempotency-Key header of up to 200 characters: creating a bare metal service, creating an IP block, creating an order, and assigning or unassigning a service on a virtual network. Send a fresh value for each new action and the same value when you retry that action.

The three create calls share one set of keys per organization, and a key is never forgotten. A retry with the same key and the same purchase (billing cycle, promo code and items) places nothing new and answers with what the first request created; Create order then answers 200 in place of 201, with data.replayed set to true. The same key with a different purchase is refused with 409 IDEMPOTENCY_KEY_REUSED. While the first request is still running, a retry gets 409 ORDER_CREATION_IN_PROGRESS with Retry-After: 5; send it again after that many seconds.

On the virtual network calls a key belongs to the service in the body, and it is remembered until 90 days after the change has been applied. A retry answers 202 again without queuing a second change, and the same key with another network or segment gets 409 IDEMPOTENCY_KEY_REUSED. A second change while the first is still being applied gets 409 NETWORK_CHANGE_IN_PROGRESS with Retry-After: 10.

Rate limits

Each API key has its own limits:

Polling a deployment every 20 seconds, as the guides do, uses 3 reads a minute.