Cloud API

The HTTP API behind cloud runs and simforge login: what it covers, how to authenticate and how errors look.

The Cloud API is what the simforge CLI calls when you add --cloud, sign in with simforge login, install the runtime or pull a map. Everything the CLI does over the network is documented here, so a script, a CI job or the Python client can do the same.

SimForge Cloud is open in beta: on simforge.ai the run endpoints work alongside the account and download endpoints (me, api-keys, distribution/*, telemetry, health). New accounts start with $25 in free credits; credit purchases aren’t open during the beta. The playground here calls https://dev.simforge.ai.

Two families of routes

Prefix	What	Errors
/api/v1	Runs (renders, simulations, Recast log ingestion, transfers), recordings and uploads, scenarios, datasets and exports, maps and vehicles, hosted authoring, runtime and map downloads, telemetry, API keys and usage.	{"error": {"code", "reason", "detail?", "path?", "requestId"}}
/api/cli	simforge login (OAuth 2.0 device and browser sign-in), the session behind a token, scenario pull, the renderer benchmark and the driving challenge.	{"error", "error_description"} (OAuth style)

Every /api/v1 response carries X-Request-Id; quote it when you report a problem.

Authenticate

Send a bearer token in the Authorization header. Each endpoint lists the scopes the credential must hold.

• An API key (sfk_…), for scripts, CI and this playground. It acts in the workspace it was created in.

  simforge login --scope keys:admin
  simforge keys create --name playground --expires-in-days 7
  

  The secret is printed once. Keep it out of shell history and source control.

• A CLI access token (sfc_at_…), which simforge login obtains with the device flow on the Sign-in endpoints and refreshes on its own. The CLI keeps it in the system keychain and never prints it.

curl -H "Authorization: Bearer $SIMFORGE_API_KEY" https://dev.simforge.ai/api/v1/me

Money and limits

Cloud runs cost money. Create a run with "dryRun": true first to get costEstimateCents, then submit with a maxCostCents no higher than your budget: a run never costs more than its cap. Send an Idempotency-Key header with every POST /api/v1/runs, so resending a lost request returns the original run instead of starting (and charging for) a second one.

Machine-readable

The whole reference is one OpenAPI 3.1 document: simforge.ai/docs/openapi.json. The Python client’s models are generated from it.