The list fields plus IP addresses, OS, hardware and delivery state. Stored blocks carry their own as_of or are "unavailable". No request ever calls the server's network live.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Data used in the current period and the allowance. used_bytes is "unavailable" (never zero) when no current figure is stored or the window reaches back before this account held the server.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Queues a PTR change for an IP of this server. The IP must be on the server's stored IP list. At most one open request per IP and 20 per server per day. Applied shortly afterwards, not in the request. On servers where it is carried out as an action, and always for hostname "" (clear the PTR), the answer is RdnsQueued with an action id to poll; another hostname for an IP with an open action is 409 server_busy.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Idempotency-Keyrequired
header
string ^[A-Za-z0-9_-]{8,64}$
8 to 64 letters, digits, dashes or underscores. One per intended action; reuse it only to retry the same request.
Request body
JSON object RdnsRequest. Unknown fields are refused.
Records a power action and returns at once (202). Poll GET /actions/{id}. The key's server list must cover the server. One action per server at a time; ceilings per server and per account per rolling hour; a burst of power-offs pauses API power for the account.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Idempotency-Keyrequired
header
string ^[A-Za-z0-9_-]{8,64}$
8 to 64 letters, digits, dashes or underscores. One per intended action; reuse it only to retry the same request.
Request body
JSON object PowerRequest. Unknown fields are refused.
GET/actions/{id}/credentialspermission: readBeta — rolling out
Beta. The password (or rescue login) of a reinstall or rescue action that was made with return_password true. Needs read; only the key that started the action, after the action is done. The first read returns it and wipes it; unread credentials are wiped after 24 hours. Every read is audited and the owner is emailed. Afterwards, before the action is done, for another key, for an action without return_password, or when the password could not be kept (action reason password_unavailable): 404 not_found. While a switch is off (platform, layer, pause) the answer is 503 unavailable and the password is kept for a later read. HEAD is refused (405) so that nothing can consume the password without reading it. Do not retry this request after a network error or a 5xx answer: the lost answer may already have used the one read (retrying after 429 rate_limited is safe).
Parameters
Name
In
Type
Description
idrequired
path
string ^act_[1-9][0-9]{0,9}$
A typed id (act_<number>). Another prefix, a leading zero or anything encoded is 404.
Orders one instant server, paid from account credit. Run it first with ?dry_run=true (no Idempotency-Key needed) and send the returned total as expected_total. Then poll GET /orders/{id} until every service is ready.
Parameters
Name
In
Type
Description
dry_run
query
"true"
true only: check and price the order; nothing is created or reserved. No Idempotency-Key needed.
Idempotency-Key
header
string ^[A-Za-z0-9_-]{8,64}$
Required for a real order (8 to 64 letters, digits, dashes or underscores); not needed with dry_run=true.
POST/servers/{id}/cancel-requestpermission: cancelBeta — rolling out
Beta. Files a cancellation at the end of the billing period (the server keeps running until then) for an active or suspended server. The owner is emailed. When a request already exists it is returned (200). Covered by the key's server list. At most 2 per account per day. 409 server_busy while a request to keep the server is less than a day old.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Idempotency-Keyrequired
header
string ^[A-Za-z0-9_-]{8,64}$
8 to 64 letters, digits, dashes or underscores. One per intended action; reuse it only to retry the same request.
DELETE/servers/{id}/cancel-requestpermission: cancelBeta — rolling out
Beta. Asks RedSwitches staff to withdraw the cancellation (filed once; repeating it changes nothing). Nothing is un-cancelled automatically. 404 when there is no cancellation request.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Idempotency-Keyrequired
header
string ^[A-Za-z0-9_-]{8,64}$
8 to 64 letters, digits, dashes or underscores. One per intended action; reuse it only to retry the same request.
POST/servers/{id}/rescuepermission: rescueBeta — rolling outoff unless RedSwitches turns it on
Beta. Off unless RedSwitches switches rescue on. Records a rescue action (202) that boots the server into rescue mode, as the portal's Rescue tab does. With return_password true the rescue login can be read once from GET /actions/{id}/credentials after the action is done. Leave rescue with POST /servers/{id}/power {"action":"reboot"}. Covered by the key's server list. At most 4 per server per day. 503 unavailable while RedSwitches has reinstalls and rescues paused.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Idempotency-Keyrequired
header
string ^[A-Za-z0-9_-]{8,64}$
8 to 64 letters, digits, dashes or underscores. One per intended action; reuse it only to retry the same request.
Request body
JSON object RescueRequest. Unknown fields are refused.
POST/servers/{id}/reinstallpermission: reinstallBeta — rolling outoff unless RedSwitches turns it on
Beta. Off unless RedSwitches switches reinstall on. Records a reinstall action (202) with the chosen saved SSH keys. No password is returned unless return_password is true (then readable once from GET /actions/{id}/credentials); otherwise, if one is set, it is emailed to the owner as in the portal. Covered by the key's server list. At most 2 per server and 5 per account per day. 503 unavailable while RedSwitches has reinstalls paused.
Parameters
Name
In
Type
Description
idrequired
path
string ^srv_[1-9][0-9]{0,9}$
A typed id (srv_<number>). Another prefix, a leading zero or anything encoded is 404.
Idempotency-Keyrequired
header
string ^[A-Za-z0-9_-]{8,64}$
8 to 64 letters, digits, dashes or underscores. One per intended action; reuse it only to retry the same request.
An instant server on offer. Prices are per billing cycle, excluding tax, in the account's currency, for the default configuration. Use a dry-run order for the exact total.
Why used_bytes is unavailable: nothing current is stored, or the measured window starts before this account held the server. Null when used_bytes is a number.
billing_period: the account's billing month. last_30_days: the network's rolling 30-day total. since_ownership: counted from when this account started holding the server.
The requests applied by the scheduled job come first (oldest first), then up to 20 changes carried out as actions (newest first). To find the newest entry for an IP, sort by requested.
For failed and unknown actions. A done action has none, except password_unavailable (a reinstall or rescue started, but the password asked for could not be kept) and not_tracked. Null otherwise or when there is no public word for it.
action_limit: the ceiling (an integer). cap_reached: the limit in force: an integer for servers_day, servers_month and open; an amount in the account's currency (minor units) for money_month, renewal_month and key_month.
window
"day" | "30_days" | "open"
cap_reached: the window of the limit: day (servers_day), 30_days (servers_month, money_month, renewal_month, key_month), open (paid orders not delivered yet; no time window).
An image id from GET /servers/{id}/os (img_…; the order's os_… ids are refused with 400).
ssh_key_idsalways
array of string ^sshkey_[1-9][0-9]{0,9}$
1 to 10 saved keys to install.
hostname
string
Optional. Lower-case letters, digits, dots and dashes.
raid
"none" | "raid0" | "raid1" | "raid10"
Optional; only on servers that offer a RAID choice (else 422 not_supported).
return_password
boolean
Optional, default false. True: the root password set by the reinstall can be read ONCE from GET /actions/{id}/credentials after the action is done (within 24 hours). False: it is never returned (emailed to the owner as in the portal).
Optional, default false. True: the rescue login can be read ONCE from GET /actions/{id}/credentials after the action is done (within 24 hours). False: the rescue login is delivered as in the portal.
This request must not have a body. A GET, HEAD or DELETE request carried a body.
400
idempotency_key_required
This request needs an Idempotency-Key header of 8 to 64 letters, digits, dashes or underscores. A POST or DELETE without a valid Idempotency-Key header (not needed for an order dry run).
400
invalid_body
The request body is not valid JSON of the documented shape for this endpoint. Unknown fields are refused. Missing body, not JSON, not one object, a duplicate name, an unknown field, a wrong type, a value of the wrong shape, Content-Type not application/json, or over 4 KB. When one field is at fault, details.field and details.reason name it and the message becomes "The request body is not valid: <field>: <reason>." (fixed texts; your value is never echoed).
400
invalid_parameter
A query parameter is not allowed here or its value is not valid. See the API documentation for this endpoint. An unknown, repeated, empty or malformed query parameter.
400
key_in_url
API keys are accepted only in the Authorization header. A working key sent in a URL is revoked. A key-shaped string was found anywhere in the URL. Every working key found there is revoked and its owner is emailed.
401
invalid_key
Missing or invalid API key. Send it as "Authorization: Bearer <key>".
401
key_expired
This API key has expired.
401
key_revoked
This API key has been revoked. Also after a security event on the account (password, email or two-factor change, API access turned off).
401
test_key
Test keys cannot be used on the live API.
402
insufficient_credit
The account credit that may be spent through the API does not cover this order. Add funds in the client area. details.needed holds the amount missing.
403
account_blocked
API access for this account is blocked. Please contact support.
403
account_inactive
This account is not active.
403
api_not_enabled
API access is not enabled for this account.
403
cap_reached
This order would go over a limit of this key or of the account. Nothing was ordered. details.cap names the limit, details.limit its value and details.window its window. Account limits are set by RedSwitches; contact support to raise one.
403
cooling_off
Ordering opens 24 hours after it was turned on and after a new ordering key. details.retry_after and the Retry-After header: seconds until ordering opens.
403
email_not_verified
The account owner must verify their email address before the API can be used.
403
ip_not_allowed
This key cannot be used from your IP address. The key has an IP allow-list that does not include the caller.
403
not_eligible
This account cannot order through the API right now. The account owner can see the reason on the API page. An eligibility check failed (for example the key has no spend cap).
403
not_invited
API access is by invitation only for now.
403
ordering_not_enabled
Ordering through the API is not turned on for this account. The owner turns it on on the API page. The account's ordering switch is off.
403
ordering_paused
Ordering through the API is paused by RedSwitches. Nothing was ordered. Try again later. RedSwitches paused API ordering.
403
owner_changed
This API key was created by a user who no longer owns the account. The owner must create a new key.
403
permission_denied
This API key does not have the permission this endpoint needs. Also when a power key's server list does not cover the server.
403
power_paused
Power actions through the API are paused for this account. RedSwitches staff have been told. Power is paused for the account, for example after a burst of power-offs.
404
not_found
Nothing was found at this address: no such endpoint, or no such item on this account. Another account's item gives the identical answer.
405
method_not_allowed
This endpoint does not take this method. The Allow header lists the methods it takes. The Allow header lists the methods of the path (HEAD is not taken by GET /actions/{id}/credentials).
409
in_progress
A request with this Idempotency-Key is still being processed. Ask again with the same key in a few seconds. details.retry_after and the Retry-After header: seconds to wait. Retry with the same Idempotency-Key and body.
409
order_not_placed
The order could not be completed and nothing was charged. RedSwitches staff have been told.
409
order_under_review
This order needs a check by RedSwitches staff before it continues. Do not repeat it; you will hear from us. details.order names the order when one was created.
409
price_changed
The total is not the expected_total that was sent. Nothing was ordered. The current total is in the details. details.total holds the current total.
409
server_busy
Another action on this server is queued, running or unsettled. Wait until it has finished, then try again. Also while the server is being delivered or installed.
409
server_not_active
This server is not active (pending, suspended or ended), so this action is not available.
409
sold_out
This server is not in stock any more. Nothing was ordered.
409
ssh_key_conflict
That key is already saved on this account, or the account holds the most keys it can.
413
body_too_large
The request body is larger than 16 KB. Refused before the API reads it.
422
idempotency_conflict
This Idempotency-Key was used for a different request. Use a new key for a new order. Same key and Idempotency-Key, different body or target.
422
invalid_ssh_key
That is not a valid SSH public key.
422
ip_not_on_server
That IP address is not assigned to this server.
422
not_orderable
This offer cannot be ordered with these choices through the API. Unknown or hidden offer, an OS that is not one of the offer's, an SSH key not on the account, a billing cycle the key does not allow.
422
not_supported
This server does not support that through the API.
429
action_limit
This would go over a limit of the account for this action (see the details). Nothing was changed. Try again later. details.limit and details.per.
429
rate_limited
Too many requests. Wait for the number of seconds in the Retry-After header.
500
internal_error
Something went wrong on our side. Quote the request id when you contact support.
503
unavailable
The API is temporarily unavailable. The API, a part of it or a dependency is switched off or not answering. Nothing was done.