> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> 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.

  ```sh theme={null}
  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.

```sh theme={null}
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](https://simforge.ai/docs/openapi.json). The Python client's models are generated from it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.