Introduction - Simnet

Overview

The console is built on this API. There is no private back channel — every screen in the guides is calling the same endpoints documented here, so anything you can do in the interface you can do programmatically.

Base URL: https://api.stg.simnet.cloud Version prefix: every path begins /api/v1 Authentication: an OAuth 2.0 bearer token — see Authentication

Staging is the only deployed environment. The console is at app.stg.simnet.cloud, the API at api.stg.simnet.cloud, and these docs at docs.stg.simnet.cloud. There is no production host yet, so treat data here as impermanent.Note that the token audience is https://api.simnet.cloud — without the stg. It is an identifier, not an address, and it does not change between environments. See Authentication.

Read this before you plan an integration. The only credential available today is the access token from a signed-in console session — a personal, short-lived token carrying your full account access. There are no API keys, client secrets or service accounts yet, so nothing can authenticate unattended.Machine credentials with role-based access control are on the roadmap. Until then, the API is for scripting your own account and prototyping, not for building a service on. See Authentication.

What this reference covers

The customer-facing v1 surface: 453 operations across 33 areas, generated from the platform source so the paths, parameters and request schemas match what the service actually accepts.

Administrative endpoints — anything under /api/v1/admin, or gated on the simnet:admin permission — are not part of the public contract and are deliberately absent. So are the platform’s internal plumbing routes. If you find a path that isn’t in this reference, treat it as unsupported and subject to change without notice, however well it appears to work.

The shape of a request

Four things determine what a call does: the token says who you are, the region header says where the work happens, the path says what you are acting on, and the body says what to do.

Element	Where it goes	Notes
Identity	`Authorization: Bearer <token>`	Required on every call. Authentication
Region	`X-Region-Context: <region uuid>`	Optional but usually wanted. Regions
Resource	The path	Always prefixed `/api/v1`
Payload	JSON body, or query parameters	Varies by operation; several creates take query parameters rather than a body

Start here

Authentication

Getting a token, and what it is allowed to do.

Regions

Targeting the right region, and what happens when you don’t.

Conventions

Pagination, filtering, and the response envelopes.

Asynchronous work

Why a create returns a job id, and how to follow it.

Errors

The one error shape, and what each status actually means.

Duplicates and aliases

Where two paths do the same job, and which to prefer.

Your first call

List the zones available to you. It needs nothing but a token, so it is the quickest way to confirm your credentials work.

curl https://api.stg.simnet.cloud/api/v1/zones \
  -H "Authorization: Bearer $SIMNET_TOKEN"

import os, requests

r = requests.get(
    "https://api.stg.simnet.cloud/api/v1/zones",
    headers={"Authorization": f"Bearer {os.environ['SIMNET_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

const res = await fetch("https://api.stg.simnet.cloud/api/v1/zones", {
  headers: { Authorization: `Bearer ${process.env.SIMNET_TOKEN}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

A 401 means the token is missing, expired, or issued for the wrong audience. A 403 with "You don't have an active account in any region yet" means the token is fine but your account has no region — activate one before going further.

A worked example: deploy an instance

Four calls: pick a zone, pick an offering, pick an image, then deploy.

Choose a zone

curl https://api.stg.simnet.cloud/api/v1/zones \
  -H "Authorization: Bearer $SIMNET_TOKEN"

Keep the zone’s id.

Choose a compute offering

curl https://api.stg.simnet.cloud/api/v1/offerings/compute \
  -H "Authorization: Bearer $SIMNET_TOKEN"

This is vCPU and memory. Keep the id.

Choose a template

curl "https://api.stg.simnet.cloud/api/v1/templates?templateFilter=executable" \
  -H "Authorization: Bearer $SIMNET_TOKEN"

Keep the id of an image whose zone matches step 1.

Deploy

curl -X POST https://api.stg.simnet.cloud/api/v1/compute/instances \
  -H "Authorization: Bearer $SIMNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceOfferingId": "b7f1c2e0-...",
    "templateId":        "9a4d51c8-...",
    "zoneId":            "1f0b7a33-...",
    "name":              "web-01",
    "startVm":           true
  }'

The response carries a jobId. The instance exists before its network interface, volumes and any public address do, so poll the job rather than assuming the work is finished — see Asynchronous work.

Deploying into a zone that doesn’t offer your chosen template or offering fails with 422 and a detail explaining which. Fetch all three lists against the same region and zone, and that class of failure disappears.

Interactive reference

Every operation in the Endpoints section is generated from the platform source and rendered with a request builder, so you can send a real call from the page with your own token, and copy the result as cURL, Python, TypeScript, Go or a handful of others.

The spec is committed at api-reference/openapi.json. If you generate clients, build them from that file rather than scraping these pages.

​Overview

​What this reference covers

​The shape of a request

​Start here

Authentication

Regions

Conventions

Asynchronous work

Errors

Duplicates and aliases

​Your first call

​A worked example: deploy an instance

​Interactive reference

Overview

What this reference covers

The shape of a request

Start here

Your first call

A worked example: deploy an instance

Interactive reference