API Overview

Everything the portals do, the Circloud® NEST API does as plain HTTP calls: VPCs, subnets, pods, cloud storage, public addresses, firewall rules, whole application topologies in one call. The API carries its own complete reference (below); this page is what to read before it.

Your credentials file

Three values reach the API from a project: where it is, who you are, and your token. The user portal hands them out as one file, with your default container registry — Config → Authentication → Download credentials, credentials.json:

{
  "api_url": "https://api.YOUR_DOMAIN",
  "tenant_id": "00000000-0000-0000-0000-000000000000",
  "token": "your-api-token",
  "default_docker_registry": {"server": "ADD_YOUR_DOCKER_REGISTRY_URL_HERE",
                              "username": "ADD_YOUR_DOCKER_REGISTRY_USERNAME_HERE",
                              "password": "ADD_YOUR_DOCKER_REGISTRY_PASSWORD_HERE"}
}

default_docker_registry is the registry to push images to: the one you set as your default on Config → Registry (Set default), with its server, username and password. Without a default it holds these placeholders, so your AI agent asks you for a registry before it pushes.

Put it at the root of your project as it is, next to your README, and keep it out of version control (the app template's .gitignore already lists it). The template's deploy.sh, upgrade.sh and destroy.sh read it, and so does your AI agent. Rotating the token on the Authentication card makes the file stale: download it again.

The administrator's file is the same format with the admin token in place of the tenant's ID and token — the admin portal's Config → Admin Authentication → Download credentials:

{
  "api_url": "https://api.YOUR_DOMAIN",
  "admin_token": "your-admin-token"
}

A script or an agent that manages the platform sends it as X-Admin-Token. The admin token reaches every tenant: keep this file out of version control above all.

The reference

The API publishes its own reference, generated from the code it runs, so it cannot drift from the API you are calling. No token is needed to read it.

A route's description is its contract: who may call it (Admin only when it is), what it does, every status it answers and why. A tag's description explains the feature — Cloud Storages, Security Rules, Topology, the operations log. The overview at the top covers authentication, the shape of an error (detail, with a code to branch on where there is one), rate limits, retries, and how to follow long work.

Scripts and AI agents

1. Read credentials.json.
2. Fetch <api_url>/openapi.json — the whole API.
3. Call the API with X-Auth-Token: <token> (the administrator's file: X-Admin-Token: <admin_token>). Four routes authenticate from the request instead, and the reference says so on each: creating a VPC, a subnet and a pod take tenant_id and token in the body; the whole-topology call takes the tenant id in its path and the token in the body.

API_URL=$(python3 -c 'import json; print(json.load(open("credentials.json"))["api_url"])')
TENANT_ID=$(python3 -c 'import json; print(json.load(open("credentials.json"))["tenant_id"])')
TOKEN=$(python3 -c 'import json; print(json.load(open("credentials.json"))["token"])')

# The whole reference
curl -sS "$API_URL/openapi.json"

# Your pods
curl -sS "$API_URL/pods" -H "X-Auth-Token: $TOKEN"

The deployable app template does all three: its cloud/deploy.sh builds and pushes your images, then posts cloud/topology.json to POST /tenants/{tenant_id}/topology with the token from credentials.json; upgrade.sh rolls a new image with POST /pods/{pod_id}/restart; destroy.sh deletes the VPCs. Its CLOUD_README.md tells an agent the same three steps.