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

# TypeScript SDK reference

> Constructor options, workspace scope, public operations, and environment helpers.

`StateMachines` is the client class of `@usestatemachines/sdk`. This page describes version 0.6. To move from 0.5, see [Upgrade from SDK 0.5 to 0.6](/sdk-api/upgrading).

## Constructor options

| Option | Behavior |
| - | - |
| `apiKey` | API key or member access token. Defaults to `STATEMACHINES_API_KEY` where a process environment exists. |
| `baseUrl` | Management API origin. Defaults to `https://api.usestatemachines.com`. The SDK adds `/v1` resource paths. |
| `workspaceId` | Default workspace for scoped calls that do not supply one. |
| `fetch` | Custom fetch implementation, used for both management calls and `credentials.fetch()`. Defaults to the runtime's fetch. |
| `attemptTimeoutMs` | Positive, finite timeout for each management HTTP attempt. Each retry gets a fresh timeout. Defaults to 60000 (60 seconds). It does not configure native app requests. |

The SDK does not load `.env` files. A missing key, or a key that contains anything other than printable ASCII, including a space, throws `TypeError` in the constructor. Invalid `attemptTimeoutMs` throws `RangeError`.

## Workspace scope

An API key belongs to one workspace. A `workspaceId` option does not grant it access to another workspace. Member access tokens need a workspace for workspace-scoped calls, supplied in the constructor or the individual input.

The constructor default applies to `environments.create()`, `environments.list()`, and `snapshots.list()`. It also applies to `auditEvents.list()` when there is no `environmentId` filter. An explicit input `workspaceId` takes precedence. Calls that identify a resource by ID use that resource's workspace and still check authorization.

`sm.me()` returns the principal, the `user` when the caller is a member, the current `organization`, the `organizations` the caller belongs to, permissions, workspace, and limits. `workspaceId` and `limits` can be null. Limits include `concurrentEnvironments` and the default and maximum `timeLimitMinutes`.

`sm.workspaces.list({ archived, limit, cursor })` reads workspace metadata. The `archived` filter is the string `'true'` or `'false'`, with `'false'` as the default. An API key sees its own workspace. `sm.workspaces.get(workspaceId)` reads one workspace. The public SDK does not create or archive workspaces.

## Public operations

| Method | Input and result |
| - | - |
| `sm.me()` | Returns the caller's identity, scope, permissions, and limits. |
| `sm.apps.list(query?)` | Returns one page of apps. Query accepts `limit` and `cursor`. |
| `sm.apps.versions(appId, query?)` | Returns one page of published and retired versions, including APIs, actors, and `isDefault`. |
| `sm.workspaces.list(query?)` | Returns one page of visible workspaces. |
| `sm.workspaces.get(workspaceId)` | Returns workspace metadata. |
| `sm.environments.create(input, options?)` | Creates from `apps` or `snapshotId`. Waits for `running` by default. |
| `sm.environments.list(query?)` | Returns one page of environments with helpers. |
| `sm.environments.get(environmentId)` | Returns an environment with helpers, including deleted metadata. |
| `sm.environments.update(environmentId, body)` | Changes `name`, `labels`, or both. `name: null` clears the name. `labels` replaces the whole map. |
| `sm.environments.pause(environmentId, options?)` | Returns the paused environment when the API accepts the change. |
| `sm.environments.resume(environmentId, options?)` | Resumes a paused or failed environment. Waits for `running` by default. |
| `sm.environments.delete(environmentId, options?)` | Returns the deleted environment. Safe to repeat. |
| `sm.environments.wait(environmentId, options)` | Reads until `options.status` is reached or the wait fails. |
| `sm.environments.connect(environmentId, appName, options?)` | Returns [app credentials](/environments/credentials), optionally for `actorId`. |
| `sm.snapshots.create(input, options?)` | Accepts `{ environmentId, name? }`. Waits for `ready` by default. |
| `sm.snapshots.list(query?)` | Returns one page of snapshots. |
| `sm.snapshots.get(snapshotId)` | Returns snapshot metadata and save status. |
| `sm.snapshots.update(snapshotId, { name })` | Renames a snapshot. `name: null` clears its name. |
| `sm.snapshots.delete(snapshotId)` | Deletes a ready or failed snapshot. Safe to repeat. A saving snapshot cannot be deleted. |
| `sm.snapshots.wait(snapshotId, options)` | Reads until `options.status` is reached or the wait fails. |
| `sm.requests.list(query)` | Returns one page of recorded calls for the required `environmentId`. |
| `sm.requests.get(requestId)` | Returns a recorded call with headers and body previews. |
| `sm.requests.stats(query)` | Returns counts and latency for an environment and time window. |
| `sm.requests.body(requestId, direction)` | Returns recorded bytes as `Uint8Array`. `direction` is `'request'` or `'response'`. |
| `sm.auditEvents.list(query?)` | Returns one page of management audit events for a workspace or environment. |

A snapshot is plain data and has no bound methods. [Requests and audit events](/environments/observability) covers recorded bodies, time windows, and audit events.

## List filters

Every `list()` method and `apps.versions()` accept `limit` and `cursor`. [Read every page of a list](/sdk-api/pagination) shows the cursor loop. The additional filters are:

| Method | Filters |
| - | - |
| `apps.list()` and `apps.versions(appId)` | No additional query filters. Versions include retired entries. |
| `workspaces.list()` | `archived: 'true'` or `'false'`, selecting archived or active workspaces. |
| `environments.list()` | `workspaceId`, `status` array, `snapshotId`, `search` for part of the name, and `label` array. |
| `snapshots.list()` | `workspaceId`, `environmentId`, and `status` array. |
| `requests.list()` | Required `environmentId`, plus the request filters in [Requests and audit events](/environments/observability#recorded-requests). |
| `auditEvents.list()` | `workspaceId` or `environmentId`. An environment filter sets the scope. An explicit workspace that conflicts with it fails. |

Environment labels use `key=value` strings. Every supplied label must match. A status array selects any listed status. Environment and snapshot lists are newest first. A page is a read at that time, not a frozen export of the full result set.

## Operation options

| Operation | Options |
| - | - |
| Environment and snapshot creation | `wait`, `timeoutMs`, `signal`, `idempotencyKey` |
| Environment resume | `wait`, `timeoutMs`, `signal` |
| Environment pause and delete | `signal` |
| Environment and snapshot wait | Required `status`. Optional `timeoutMs` and `signal` |
| Connect | Optional `actorId` |

`wait` defaults to true. With `wait: false`, creation and resume return after acceptance. `timeoutMs` bounds the subsequent wait, starting after the initial operation returns. It is not a deadline for the combined creation and waiting time. With `wait: false`, `timeoutMs` has no effect.

A create call without `idempotencyKey` generates one UUID and reuses it across automatic retries. Separate create calls generate separate keys. [Operation recovery](/sdk-api/recovery) explains how to preserve one key across application retries.

`signal` cancels caller-side work. It does not roll back an accepted operation. Only environment create, pause, resume and delete, snapshot create, and the two `wait()` methods accept `signal`.

A wait's `timeoutMs` defaults to 600000 (10 minutes). Polling starts at 1 second, multiplies the interval by 1.5 up to 5 seconds, and varies each interval at random by up to 20 percent. Each poll read times out after 30 seconds.

## Environment helpers

Returned environments have `connect()`, `pause()`, `resume()`, `delete()`, `refresh()`, and `snapshots.create()` bound to their ID. The bound snapshot helper accepts `{ name? }` and the same creation options as `sm.snapshots.create()`.

Helpers are not enumerable. `JSON.stringify(env)` and object spread preserve API data, not methods. A parsed JSON environment must be read again through `sm.environments.get(id)` to obtain helpers.

An environment object is one resource read. Operations return new objects. They do not change a previously returned object's `status`. `refresh()` reads the current state. Explicit waits are on `sm.environments.wait()`, not on the environment object.

## Runtime and type support

The SDK is ESM only. Node.js support follows the package's `engines` field. TypeScript projects need fetch types through the DOM library or Node.js types. Response timestamps are `Date` objects in the SDK. Direct HTTP responses use timestamp strings.

Public types and the error classes are exported from `@usestatemachines/sdk`. Response enums can contain values introduced after the installed SDK, so callers need a fallback for unfamiliar statuses. Polling keeps waiting on an unfamiliar status until its deadline.

The SDK belongs in trusted server processes. A management API key must never be included in browser JavaScript. Cloudflare Workers use an explicitly supplied key. See [Use the SDK in Cloudflare Workers](/sdk-api/workers).


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