Using the API

⏱ 6 min read 🟡 Intermediate Last updated: October 2026

Everything you can do in the console, you can also do from code. The API lets scripts, CI pipelines and your own tools launch servers, change firewall rules, take snapshots and more.

What the API is for

Automation: create a server for a job, run it, then delete it.
Deployments: take a snapshot from your CI pipeline before you deploy.
Scaling: add servers when you're busy and remove them afterwards.
Reporting: pull your servers and usage into your own tools.

Create an API key

In the console, open Developer › API Keys.
Click + New Key and give it a name that says what uses it, such as ci-deploy.
Copy the key. It starts with bm_ and is shown only once.

ℹ️ You need to be an organisation admin or owner to create keys. A key belongs to the organisation, not to you, and works across its projects.

Your first request

All requests go to https://console.baremeta.cloud/api/v1. Send your key in the X-API-Key header. Store it in an environment variable rather than typing it into commands:

export BAREMETA_API_KEY="bm_..."

curl https://console.baremeta.cloud/api/v1/orgs \
  -H "X-API-Key: $BAREMETA_API_KEY"

This lists your organisation. Use its id to list projects, and a project's id to list its servers:

curl https://console.baremeta.cloud/api/v1/orgs/<org_id>/projects \
  -H "X-API-Key: $BAREMETA_API_KEY"

curl https://console.baremeta.cloud/api/v1/projects/<project_id>/vms \
  -H "X-API-Key: $BAREMETA_API_KEY"

💡 You can also find your organisation and project IDs in the console's API Reference, where every example is pre-filled for the project you have selected.

Launch a server

curl -X POST https://console.baremeta.cloud/api/v1/projects/<project_id>/vms \
  -H "X-API-Key: $BAREMETA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: web-01-launch-1" \
  -d '{"name":"web-01","image":"ubuntu-24.04","vcpus":2,"memory_mb":4096,"disk_gb":50,"assign_public_ip":true}'

The server starts building straight away. Check on it by listing the project's servers until its status is running. Servers launched from the API are billed exactly like servers launched in the console.

Retrying safely

Networks fail. If a request to create something times out, you can't tell whether it worked. Add an Idempotency-Key header with a value you choose to every POST, PUT or PATCH:

Retry with the same key and same body within 24 hours and nothing is done twice. You normally get the original response back.
Launching a server is the exception: its response includes a one-time password that we do not store, so a retry returns 410 with the code idempotency.response_not_stored. The server was still created, once. List the project's servers to find it.
Reuse a key with a different body and the request is refused, so a typo can't silently do the wrong thing.
Use a new key for each new action.

Errors

Errors come back as JSON with a short code, a readable message and a request ID:

{"error": {"code": "...", "message": "Invalid API key", "status": 401, "request_id": "5e5405d48d80"}}

401: the key is missing, wrong, revoked or expired.
403: the key is valid but can't do this (see below).
404: the resource doesn't exist, or your organisation can't see it.
409 / 422: the request conflicts with the current state, or a field is invalid. The message says which.
429: too many requests. Wait a moment and retry.

If you contact support about a failed request, include the request_id.

What keys can't do

API keys are for running your infrastructure, not for managing people or access. These actions need you to be signed in to the console:

Creating or revoking API keys
Managing organisations, projects and members
Adding or removing SSH keys
VPN credentials
Opening the browser terminal or resetting a server password
Billing settings, account security and your personal profile

This means a leaked key can't lock you out of your account or create more keys.

Keeping keys safe

⚠️ Treat an API key like a password. Anyone who has it can create, change and delete servers in your organisation, and those servers are billed to you.

Use one key per tool or pipeline, so you can revoke one without breaking the others.
Keep keys in your CI's secret store or an environment variable. Never commit them to Git or paste them into tickets.
The API Keys page shows when each key was last used. Revoke any you don't recognise or no longer need.
Changing your password or two-factor settings revokes the keys you created, so update your pipelines afterwards.
Set a spending cap to limit what a runaway script can cost. It is checked hourly, so it is a backstop, not a hard stop.

Full reference

The console's Developer › API Reference lists every endpoint you can use, grouped by area, with a ready-to-run example for each one. The examples use a signed-in session token; replace the Authorization header with X-API-Key to use a key instead.