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

# Management API reference

> HTTP authentication, lifecycle responses, idempotency, and the error format without the TypeScript SDK.

The management API owns State Machines resources. It is separate from the native API of an app running in an environment. The default origin is `https://api.usestatemachines.com` and resource routes use `/v1`. The [management endpoint reference](/sdk-api/endpoints) lists every public route, request field, and response shape from `openapi.json`.

## Authentication

Management calls use `Authorization: Bearer` with a State Machines API key or member access token. API keys are scoped to one workspace. `GET /v1/me` returns the caller's principal, permissions, workspace, and applicable limits.

Do not pass the management API key to Salesforce. Request app credentials through the management API, then send those credentials only to the returned app URL.

For JSON request bodies, send `Content-Type: application/json`. Use the same field names as the SDK create input. Supply exactly one of `apps` and `snapshotId`. Member tokens must identify the target `workspaceId` on workspace-scoped calls. An API key defaults to its own workspace.

## Acceptance and readiness

| Operation | Response |
| - | - |
| `POST /v1/environments` | Create an environment. Returns 202, or 200 on a replay. |
| `POST /v1/snapshots` | Create a snapshot. Returns 202, or 200 on a replay. |
| `POST /v1/environments/{environmentId}/pause` | Returns the environment after the API accepts the change. |
| `POST /v1/environments/{environmentId}/resume` | Returns the accepted environment in `starting`. |
| `DELETE /v1/environments/{environmentId}` | Returns the environment after the API accepts the change. |

A replay returns the resource as it is now. A successful environment create response means the environment exists, usually in `starting`. Poll the environment until it is `running` before making app requests. A snapshot must become `ready` before use. Unlike the SDK's default behavior, direct HTTP creation does not wait for readiness.

Pause and delete take effect when the API answers. The gateway refuses app calls from that point. Compute and data cleanup continue after the delete response, so HTTP 200 is not proof that every underlying cleanup step has finished. After resume, poll until the environment is `running` before requesting app credentials.

## Idempotency

Environment and snapshot creation accept the `Idempotency-Key` header. Pause, resume and delete also accept the header. A key is 8 to 128 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, `:` and `-`.

Replaying the same key with the same input and caller recovers the accepted operation. Changed input produces `idempotency_key_reused`. Without the header, a retried create makes a second environment. A replay does not restart a resource that has since failed or been deleted.

## Errors

Management errors return this body:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "...",
    "requestId": "req_...",
    "fields": { "name": ["..."] },
    "status": "..."
  }
}
```

`code`, `message` and `requestId` are always present. `fields` maps dotted input paths to arrays of messages. `status` is the resource status involved in an invalid operation, distinct from the HTTP status number. Both are optional.

The `Request-Id` response header also identifies the management request. Preserve the request ID when reporting a failure. Never include bearer tokens in diagnostic output. The [SDK error reference](/sdk-api/errors#management-error-codes) lists the codes and their HTTP statuses.

## Lists

Lists return `{ data, nextCursor }`. Repeated list filters use repeated query parameters, such as `status=running&status=paused` or `label=suite%3Dintegration`. HTTP time filters use RFC 3339 strings, while the SDK accepts `Date` objects. Continue with `cursor` until `nextCursor` is `null`. See [Read every page of a list](/sdk-api/pagination).

## Clients in other languages

Preserve one create key across transport retries and use bounded polling with backoff. Inspect terminal statuses before the next poll. Never send the management bearer token to an app URL. Do not retry native app writes automatically. [Recover interrupted management operations](/sdk-api/recovery) describes the caller behavior.


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