API¶

The NubeStack Cloud API does everything inside a project that the console does: instances, networks, volumes, load balancers, certificates and the rest. It is JSON over HTTPS, versioned under /v1. Changes that run in a location answer at once with 202 Accepted and an operation to follow.

Authentication

Service accounts, API keys, what a key may do, rotation.
Requests

IDs, idempotency keys, versions and If-Match, lists and pages.
Operations

Follow a change from 202 Accepted to its final state.
Errors

Problem responses, retrying, and every error code.
API reference

Every operation with its parameters, bodies and responses.
Tutorial: automate with the API

A script that creates a network and an instance, waits, and cleans up.

Before you start¶

An owner or admin creates a service account and gives it a role on the project. For your own scripts on one project, you can instead make a personal service account there.
They issue an API key for it and give it to you through a secret store, or you issue one for your personal service account.
You set these variables in your shell. The address is a placeholder: use the one NubeStack gives you, without /v1.

export NUBESTACK_API="https://api.nubestack.cloud"   # placeholder: your API address
export NUBESTACK_API_KEY="nxk_…"                      # from your secret store, never in a file you commit

Your first request¶

curl -sS "$NUBESTACK_API/v1/me" -H "Authorization: Bearer $NUBESTACK_API_KEY"

The answer says who the key belongs to and its organization's ID (org_…). Every other path starts with that organization. Set it, then list the projects the key can see:

export ORG="org_01jbacme"
curl -sS "$NUBESTACK_API/v1/orgs/$ORG/projects" -H "Authorization: Bearer $NUBESTACK_API_KEY"
export PROJECT="prj_01jbwebshop"

Locations come from GET /v1/orgs/$ORG/locations (each loc_… ID with its code, such as pak-khi-1), and each location's sizes, images and other choices from GET /v1/orgs/$ORG/catalog?location=loc_….

IDs in these docs

Real IDs are a prefix and a longer unique code, for example srv_01jbweb100000000000000001. The examples shorten them, as in srv_01jbweb1. Use the IDs your requests return.

Make a change¶

curl -sS -X POST "$NUBESTACK_API/v1/orgs/$ORG/projects/$PROJECT/volumes" \
  -H "Authorization: Bearer $NUBESTACK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"location": "loc_01jbkhi", "display_name": "data-1", "size_gb": 50}'

{
  "operation": {
    "id": "op_01jbvol1",
    "state": "queued",
    "href": "/v1/orgs/org_01jbacme/operations/op_01jbvol1"
  },
  "volume": {
    "id": "vol_01jbdata1",
    "href": "/v1/orgs/org_01jbacme/projects/prj_01jbwebshop/volumes/vol_01jbdata1"
  }
}

Then follow the operation until it succeeds. Every service page has the same change in its API tab.

What the API does not do¶

Create or delete projects, or manage people, roles, keys and settings, with a service account's key. People do these in the console; the NubeStack CLI, signed in as you, also creates projects.
Sign a person in from a script. Use a service account's API key, or the CLI's browser sign-in.
Anything a location's own OpenStack API does directly. For that, use native access.
Prices and invoices beyond the provisional usage and statements.

The contract¶

The API is described by an OpenAPI 3.1 contract: download it for your own tools and client generators. The reference is rendered from it.