Management API reference - State Machines

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 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:

{
  "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 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.

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 describes the caller behavior.

​Authentication

​Acceptance and readiness

​Idempotency

​Errors

​Lists

​Clients in other languages