Skip to main content
Use • 2 mins read

Hippius Management API

Hippius Management API

The Hippius Management API is a REST API for managing your account, S3 tokens, billing and compute programmatically. Use it to automate token rotation, check the balance, subscribe to a plan, or provision storage on demand.

What It Does​

The Management API handles everything outside of the S3 data plane:

AreaWhat you can do
Token managementCreate, list, rotate, and revoke master and sub tokens
BillingCheck the balance, top up, subscribe to Drive / S3 / Hub plans from the existing balance
AccountManage account settings and access keys
ComputeCreate and manage VMs, managed databases and Kubernetes clusters. See Compute API

For storing and retrieving files, start with Getting Started and Advanced Usage. The Management API is the control plane: it manages who can access storage and how much they can use.

Interactive Docs​

The full API specification with request/response examples is available as an interactive Swagger UI:

api.hippius.com

Use Cases​

  • CI/CD pipelines — Create short-lived sub tokens scoped to a single bucket for deployments, then revoke them automatically
  • Multi-tenant apps — Provision a bucket and scoped token per customer from your backend
  • Billing automation — Check the balance, top up, and subscribe to a plan without a browser
  • AI agents & LLMs — Automate storage operations end-to-end without manual console interaction
For AI agents and LLMs

A machine-readable index is at docs.hippius.com/llms.txt. It points at each product's own llms.txt. The long S3 ingest is docs.hippius.com/llms-full.txt.

Authentication​

Management API requests need an access token. Generate one in the Hippius Console under Settings, and send it in the Authorization header:

curl -H "Authorization: Token YOUR_TOKEN" https://api.hippius.com/api/accounts/

A few catalogue reads need no token, for example the compute sizes and prices at GET /api/compute/flavors/ and the plans at GET /api/s3/plans/ and GET /api/drive/plans/. To act in an account shared with you, add the header X-Hippius-Account: acct_.... See Shared accounts.

Compute API​

Virtual machines, managed databases and Kubernetes clusters are driven through the same API.

  • Base URL: https://api.hippius.com/api. VMs are under /compute/, databases under /databases/, Kubernetes under /kubernetes/.
  • Authentication: Authorization: Token YOUR_TOKEN, as above. Add X-Hippius-Account: acct_... to act in a shared account.
  • Specification: the OpenAPI (Swagger 2.0) document is at api.hippius.com/swagger.json, with the endpoints and their fields.

To create a VM and connect to it:

API=https://api.hippius.com/api
AUTH="Authorization: Token YOUR_TOKEN"

# 1. Pick a size, an image and a region, and find your SSH key's id
curl -s -H "$AUTH" $API/compute/flavors/
curl -s -H "$AUTH" $API/compute/images/
curl -s -H "$AUTH" $API/compute/regions/
curl -s -H "$AUTH" $API/ssh-keys/

# 2. Launch it: 202 Accepted, with the VM and its vm_id
curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "web-1", "flavor": "small", "region": "FR", "ssh_key_ids": [123]}' \
  $API/compute/vms/

# 3. Poll until it is up
curl -s -H "$AUTH" $API/compute/vms/VM_ID/

flavor and an SSH key are required: the ids of saved keys in ssh_key_ids (up to 20), or a key itself in ssh_public_key. Without image the size's default image is used, and without region one is picked for you. While the VM boots, progress shows the current step and boot_phase goes from booting to kek_released and running. Once netbird_ip is set, SSH to it from a device on your private network, or to public_ip if you launched with "public_ip": true and a firewall rule opens port 22.

A VM has two state fields:

  • status is its lifecycle: pending, provisioning, running, failed, decommissioning, decommissioned. A VM is billed while it is running, including when it is stopped.
  • power_state says whether it is on: running, stopping, stopped or starting, empty until reported, and off once the VM is deleted. A stopped VM stays running under status.
Set a User-Agent

Some HTTP clients' default User-Agent is blocked in front of the API, with 403 and error code: 1010. Python's urllib is one. Send your own User-Agent header, for example my-deploy-script/1.0.