Quickstart

Checked against the API code 3 November 2026

This page takes you from no key to the details of one of your servers.

Before you start

The login of the account owner. Only the owner sees API Management in the client area. Users added to someone else’s account do not.
At least one VPS on the account for steps 3 and 4. Without one, stop after step 2 and go to All guides.
A terminal with curl.

Steps

1. Create an API key

Log in to the client area and open API Management.
Click Create API Key.
Under Key Name, write what the key is for, for example quickstart. Leave This is a test key unticked. There is no test environment. A test key works on your real services too.
Open the Permissions tab and tick read:account and read:vm. Nothing is ticked from the start. With these two the key can read your account and your VPS. It cannot change anything.
Leave the Security tab as it is for now. That is where you limit a key to certain IP addresses or give it an expiry date. Authentication and scopes explains both.
Click Create API Key. Copy the value under Your API Key. It starts with sk_live_. The Key ID above it (key_…) is not the key. The key is shown once only.
Click I’ve saved it and then Yes, close it.

Put the key in an environment variable. Replace the text in quotes with your key. Every sample on this site reads it from $HOSTUP_API_KEY.

export HOSTUP_API_KEY="the key you copied"

The variable lasts as long as this terminal. In a new terminal, run the export again.

Keep the key out of your code and out of version control. A password manager or your platform’s secret store is a good place for it.

2. Check that the key works

GET /api/v2/me returns the account the key belongs to.

curl "https://cloud.hostup.se/api/v2/me" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

{
  "id": "client_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "name": "Alex Example",
  "email": "[email protected]",
  "authType": "api-key",
  "scopes": ["read:account", "read:vm"],
  "…": "…"
}

scopes shows what the key may do.

If you get 401

The key was not accepted (unauthorized). The most common cause is the Key ID (key_…) instead of the key. The key may also be mistyped, revoked or expired. A key limited to certain IP addresses gets 401 from any other address. In a new terminal, $HOSTUP_API_KEY is empty until you run the export again. When a key is refused lists every case.

If you get 403

The key works but lacks a scope (forbidden). requiredScopes in the answer names it. Open the key’s menu in API Management, click Edit Permissions and tick the scope. The change applies at once. Then send the request again.

3. List your VPS

GET /api/v2/vps returns your servers, 20 at a time.

curl "https://cloud.hostup.se/api/v2/vps" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

{
  "data": [
    {
      "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "name": "app-01",
      "primaryIp": "192.0.2.10",
      "serviceStatus": "active",
      "powerState": "running",
      "…": "…"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Servers that have ended are not in the list. When hasMore is true there are more servers than fit on the page. Pagination shows how to read every page.

Each server has an id that starts with vps_. Every VPS endpoint takes that ID. Keep the id of one of your servers. Step 4 uses it.

export VPS_ID="vps_…"   # the id of one of your servers above

If the list is empty

An empty list means the account has no current VPS.

If you only know the server’s IP address

Filter the list by primaryIp. Keep the URL in double quotes. Without them, some shells stop at the ? before curl runs.

curl "https://cloud.hostup.se/api/v2/vps?primaryIp=192.0.2.10" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

export VPS_ID="vps_…"   # data[0].id from that answer

IDs shows the answer and the other lookups.

4. Read one VPS

GET /api/v2/vps/{id}/details returns one server with what you need before you act on it.

curl "https://cloud.hostup.se/api/v2/vps/$VPS_ID/details" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

{
  "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "serviceStatus": "active",
  "powerState": "running",
  "actions": {
    "canRestart": { "allowed": true, "reason": null },
    "canStop": { "allowed": true, "reason": null },
    "…": "…"
  },
  "…": "…"
}

actions says what you can do with the server right now. Each entry has allowed and, when it is false, a reason. Check the matching entry before you change a VPS.

If you get 404

No VPS on your account has that ID (vps_not_found). Check that VPS_ID holds an id from step 3, not the placeholder vps_….

What every call has in common

Every request goes to https://cloud.hostup.se. The paths start with /api/v2/.
Most actions that take time answer 202 with a job. You poll it at GET /api/jobs/{jobId}, which is outside /api/v2/. Put https://cloud.hostup.se in front of the pollUrl you get, not a base URL that ends in /api/v2. Jobs explains the rest.
Every request carries Authorization: Bearer $HOSTUP_API_KEY.
Every POST, PUT and PATCH needs Content-Type: application/json. Send it even when there is no body. Without it the request fails with 415.
Responses are JSON. Errors have a stable code you can branch on.
Each API key may send 300 requests per five minutes. Requests over that are refused until the five minutes have passed. Today most endpoints then answer 500 with the code internal_error instead of 429. Keep count when a loop or a job poll could reach the limit. Rate limits says what to do.

Make your first change: Restart a VPS and wait until it is back. It needs power:vm. Open the key’s menu in API Management, click Edit Permissions and tick it.

Read these once before you build more:

Authentication and scopes: give each key only what it needs.
Errors and retries: what to retry and what to fix.
Jobs: follow a restart, a backup or an order until it is done.
All guides: one task per page, from DNS records to invoices.