Skip to main content
A sandbox is one running simulator instance. Where a Simulator is a definition (“a FHIR EHR”, “a payer portal”), a sandbox is the live, provisioned version of it: a real FHIR store you can POST Bundles to, a real phone number you can call, a real portal URL you can log into. Sandboxes live inside Playgrounds (one per simulator in the environment) and are the source of truth the verification engine reads after a rollout.

​
Playground to Sandbox

A playground has one sandbox per simulator linked to its environment. Each sandbox carries its own set of credentials, own isolated dataset branch, and own event log.

​
Credentials by Simulator Type

The shape of credentials on GET /sandboxes/{id} depends on the simulator type.
SimulatorCredentials shape
FHIRfhir_base_url (FHIR R4 endpoint), token_url (SMART on FHIR token endpoint), client_id, client_secret
Voicephone_number (E.164 number to call)
HL7inbox_url (GET inbound messages), outbound_url (POST outbound messages)
Payer / Web Portalportal_url, auto-generated username and password, api_url (REST base for the backing payer endpoints)
FaxInbound fax number and upload endpoint
Files / SFTPSFTP paths scoped to this sandbox under object storage
X12Transaction submission endpoint and response retrieval URL
CDS HooksHook registration URL
MessageSMS/text endpoint URL
All credentials are scoped to the specific sandbox. Nothing leaks across sandboxes or playgrounds.

​
Events and Interactions

Every request to a sandbox gets recorded as an event. You can list them: 
curl "https://api.verial.ai/sandboxes/$SANDBOX_ID/events" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
Events back the evidence shown in criterion runs. Common event types:
  • FHIR: HTTP method, path, body, status code, response body.
  • HL7: outbound hl7_outbound events with the full HL7v2 message.
  • Portal: form submits, patient searches, auth submissions.
  • Voice: recorded turns with speaker and transcript.
  • SFTP: file upload and download events.
See Interactions for how these feed the verification engine.

​
Dataset Branching and Checkpoints

When a dataset is linked to a sandbox, Verial creates a child dataset (parentId set) with copied config and copied GCS files. The sandbox operates on the child, so changes the agent makes (adding a Patient, uploading a file) stay isolated. A baseline checkpoint is written at branch time, storing a snapshot of the child’s config. 
# Link a dataset (branches into a child + writes a baseline checkpoint)
curl -X POST "https://api.verial.ai/sandboxes/$SANDBOX_ID/datasets/ds_abc123" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

​
Standalone vs Playground Sandboxes

CaseHow it arises
Playground sandboxCreated automatically when a playground is provisioned. playground_id is set.
Standalone sandboxCreated directly via POST /sandboxes for interactive exploration or building dataset fixtures. No playground_id.
Both shapes share the same event and dataset model.

​
Teardown

Tear down a sandbox with POST /sandboxes/{id}/teardown, or let the owning playground tear it down when the benchmark run completes. Teardown releases the live resources (FHIR store, phone number, portal credentials) while preserving the event log and any branched datasets for later inspection.

​
Creating a Sandbox

# Standalone sandbox (no playground)
curl -X POST https://api.verial.ai/sandboxes \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"simulator_id": "sim_abc123"}'
# → save the returned id as $SANDBOX_ID

# Load a dataset
curl -X POST "https://api.verial.ai/sandboxes/$SANDBOX_ID/datasets/ds_abc123" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Inspect credentials and state
curl "https://api.verial.ai/sandboxes/$SANDBOX_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Read the event log
curl "https://api.verial.ai/sandboxes/$SANDBOX_ID/events" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Release resources
curl -X POST "https://api.verial.ai/sandboxes/$SANDBOX_ID/teardown" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

​
Next Steps

Interactions

The evidence captured on each sandbox during a rollout.

Sandboxes API

REST endpoints and full object reference.