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

# Upgrade from SDK 0.5 to 0.6

> Install 0.6, rename the changed calls and error codes, and confirm one complete task.

SDK 0.6 follows the current management API. SDK 0.5 and older call routes that the API no longer serves, so they fail against it.

## Install 0.6

The SDK is ESM only and needs Node.js 20.20 or later.

```sh theme={null}
npm install @usestatemachines/sdk@0.6
```

## Update the key and host

Rename the `STATE_API_KEY` variable to `STATEMACHINES_API_KEY`. The SDK reads only the new name.

The default host is now `https://api.usestatemachines.com`. If your code passes `baseUrl: 'https://state-api.usestatemachines.workers.dev'`, delete that option.

## Rename lifecycle calls

| 0.5 | 0.6 |
| - | - |
| `sm.environments.start(input)` | `sm.environments.create(input)`, which waits until `running` |
| `sm.environments.start({ snapshotId })` | `sm.environments.create({ snapshotId })` |
| `env.stop()`, `sm.environments.stop(id)` | `env.delete()`, `sm.environments.delete(id)` |
| `env.suspend()`, `sm.environments.suspend(id)` | `env.pause()`, `sm.environments.pause(id)` |
| `env.resume()` then `env.waitUntilReady()` | `env.resume()`, which waits until `running` |
| `waitUntilReady`, `waitUntilStopped`, `waitUntilSuspended` | `sm.environments.wait(id, { status })` |

Pausing keeps the environment's data. Deleting removes it. Map each old `stop` call to `delete` only where the task is finished with the data.

## Update app entries and credentials

| 0.5 | 0.6 |
| - | - |
| Apps as `{ key, appId }` | Apps as `{ app, name }`, or the app name as a string |
| `env.connect(app, { apiId, actorId })` returns a `Connection` | `env.connect(app, { actorId })` returns `Credentials`. `fetch` picks the API from the path. |
| `connection.baseUrl`, `connection.headers()` | `credentials.url`, `credentials.headers`, `credentials.token` |
| `X-State-Environment-Token` header | `StateMachines-Environment-Token` header |

For Salesforce SOAP, put `credentials.token` in `SessionHeader/sessionId` in the envelope. See [credentials and actors](/environments/credentials).

## Update snapshots, requests and identity

| 0.5 | 0.6 |
| - | - |
| `env.snapshot(options)` | `env.snapshots.create(options)` |
| `sm.snapshots.capture(environmentId, options)` | `sm.snapshots.create({ environmentId, ...options })` |
| `sm.environments.listRequests` | `sm.requests.list({ environmentId })` |
| `sm.environments.getRequest` | `sm.requests.get(id)` |
| `sm.environments.getRequestPayload` | `sm.requests.body(id, direction)` |
| `sm.environments.getRequestStats` | `sm.requests.stats(query)` |
| `sm.credential.get()` | `sm.me()` |
| The catalog | `sm.apps.list()`, `sm.apps.versions(appId)` |

## Update error handling

| 0.5 | 0.6 |
| - | - |
| `TimeoutError` | `WaitTimeoutError` |
| `error.retryAfter` | `error.retryAfterMs` |
| `environment-limit` | `environment_limit_reached` |
| `capture-in-progress` | `snapshot_in_progress` |

Every 0.6 error code uses underscores. Check the error subclasses with `instanceof` before you read `StateMachinesError.code`. Never match message text. The [SDK error reference](/sdk-api/errors) lists the classes and codes.

## Confirm one complete task

Run the [quickstart](/get-started/quickstart) outside production. Confirm that creation reaches `running`, the app request succeeds, and deletion completes.

## Pin the minor version

A `0.x` minor release can include breaking changes. Pin the minor version in `package.json` so an install does not move you to 0.7:

```json theme={null}
{
  "dependencies": {
    "@usestatemachines/sdk": "~0.6.0"
  }
}
```


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