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

# Sandboxes

> Running simulator instances with credentials and event logs.

Sandboxes are running instances of a [Simulator](/api-reference/resources/simulators). Each sandbox provides live credentials (FHIR endpoints, phone numbers, fax numbers, SFTP paths, portal URLs) and records all interactions as events. Sandboxes can be created standalone or as part of a [Playground](/api-reference/resources/playgrounds). After a task rollout, sandbox state is the input the [verification engine](/guides/concepts/verification) scores against.

## Endpoints

| Method   | Endpoint                               | Description                       |
| -------- | -------------------------------------- | --------------------------------- |
| `GET`    | `/sandboxes`                           | List sandboxes                    |
| `POST`   | `/sandboxes`                           | Create a sandbox                  |
| `GET`    | `/sandboxes/{id}`                      | Get sandbox details               |
| `GET`    | `/sandboxes/{id}/events`               | List sandbox events               |
| `POST`   | `/sandboxes/{id}/teardown`             | Tear down a sandbox               |
| `POST`   | `/sandboxes/{id}/datasets/{datasetId}` | Add a dataset to the sandbox      |
| `DELETE` | `/sandboxes/{id}/datasets/{datasetId}` | Remove a dataset from the sandbox |

## Sandbox Object

| Field             | Type           | Description                                                                                                |
| ----------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| `id`              | string         | Unique identifier                                                                                          |
| `simulator_id`    | string         | Source [Simulator](/api-reference/resources/simulators)                                                    |
| `playground_id`   | string \| null | Parent [Playground](/api-reference/resources/playgrounds), if part of one                                  |
| `status`          | string         | Current status (provisioning, active, teardown, etc.)                                                      |
| `credentials`     | object \| null | Protocol-specific access credentials. See [Credentials by Simulator Type](#credentials-by-simulator-type). |
| `organization_id` | string         | Parent organization                                                                                        |
| `created_at`      | datetime       | Creation timestamp                                                                                         |
| `updated_at`      | datetime       | Last modification timestamp                                                                                |

## Credentials by Simulator Type

The `credentials` object is shaped by the source simulator's `type`. Typical shapes:

### Payer (Web Simulator)

Returned when the simulator's `config.portal` is set (see the [Web Portal](/guides/simulators/web-portal) catalog).

| Field        | Type   | Description                                                                               |
| ------------ | ------ | ----------------------------------------------------------------------------------------- |
| `portal_url` | string | URL for a browser agent to navigate to (e.g. `https://radmd.sim.verial.ai`)               |
| `username`   | string | Auto-generated login username, scoped to this sandbox                                     |
| `password`   | string | Auto-generated login password, scoped to this sandbox                                     |
| `api_url`    | string | REST base URL for the backing payer endpoints (`/prior-auths`, `/patients`, `/providers`) |

```json theme={null}
{
  "portal_url": "https://radmd.sim.verial.ai",
  "username": "provider_a1b2c3",
  "password": "Kq7!mZxP9vRnT2wL",
  "api_url": "https://api.verial.ai/sandboxes/sbx_01H.../web-sim/payer"
}
```

### FHIR

| Field           | Type   | Description                  |
| --------------- | ------ | ---------------------------- |
| `fhir_base_url` | string | FHIR R4 base URL             |
| `token_url`     | string | SMART on FHIR token endpoint |
| `client_id`     | string | OAuth2 client ID             |
| `client_secret` | string | OAuth2 client secret         |

### Voice

| Field          | Type   | Description          |
| -------------- | ------ | -------------------- |
| `phone_number` | string | E.164 number to call |

### HL7

| Field          | Type   | Description                   |
| -------------- | ------ | ----------------------------- |
| `inbox_url`    | string | URL to GET inbound messages   |
| `outbound_url` | string | URL to POST outbound messages |

Other simulator types follow the same pattern: connection details needed to read from and write to the live instance.

## SDK Example

```typescript theme={null}
// Create a standalone sandbox
const sandbox = await verial.sandboxes.create({
  simulatorId: 'sim_abc123',
})

// List sandboxes (optionally filter by playground)
const sandboxes = await verial.sandboxes.list({ playgroundId: 'pg_abc123' })

// Get sandbox details (includes credentials)
const details = await verial.sandboxes.get({ id: sandbox.id })

// List interaction events
const events = await verial.sandboxes.listEvents({ id: sandbox.id })

// Load a dataset
await verial.sandboxes.addDataset({
  sandboxId: sandbox.id,
  datasetId: 'ds_abc123',
})

// Remove a dataset
await verial.sandboxes.removeDataset({
  sandboxId: sandbox.id,
  datasetId: 'ds_abc123',
})

// Tear down when done
await verial.sandboxes.teardown({ id: sandbox.id })
```