Skip to main content
A playground is a running instance of an Environment. When a playground is provisioned, every simulator in the environment comes up as a live Sandbox, datasets are loaded, and credentials are returned. Task rollouts execute inside a playground, and the verification engine reads the playground’s final sandbox state to score criteria.

​
Lifecycle

  1. Created. A playground row is written referencing the source environment.
  2. Provisioning. For each simulator in the environment, Verial spins up a sandbox, allocates resources (FHIR stores under the GCP Healthcare API, leased phone numbers, portal URLs, fax numbers, SFTP paths), and branches any linked datasets into the sandbox.
  3. Active. All sandboxes are up and their credentials are available. Your agent can now drive rollouts against the sandbox endpoints.
  4. Teardown. Resources are released (FHIR stores deleted, phone numbers released back to the pool, portal users removed). Interaction logs and sandbox events are retained so you can inspect evidence after the fact.

​
What Provisioning Does

Provisioning is where the environment’s definition becomes running infrastructure:
  • FHIR sandboxes get a dedicated GCP Healthcare API FHIR store (named with a fhir- prefix), a SMART on FHIR token endpoint, and an OAuth2 client.
  • Voice sandboxes lease a phone number from the pool.
  • Portal sandboxes get a unique portal URL with auto-generated username and password.
  • Fax sandboxes lease an inbound fax number.
  • SFTP / Files sandboxes get a scoped storage prefix.
  • Datasets linked to each simulator are branched to a child dataset and loaded into that sandbox.
The full set of credentials is returned on GET /playgrounds/{id}.

​
Two Ways Playgrounds Arise

FlowCallerWhen
Explicit POST /playgroundsBenchmark authors, interactive explorationYou want to poke at an environment without running a full benchmark
Implicit from POST /benchmark-runs (or POST /v1/benchmark-runs)The run machineryVerial provisions a playground for you and passes its endpoints back to the agent
If you are running a benchmark end to end via the v1 API, you do not need to create playgrounds yourself. See the Quick Start.

​
Teardown and Retention

Tear down a playground explicitly via POST /playgrounds/{id}/teardown, or let the benchmark run do it for you when the final task run completes. Teardown releases the live resources (so phone numbers are not held forever and FHIR stores are not billed indefinitely) but preserves:
  • Every Interaction recorded during the run.
  • Every sandbox event row (FHIR request log, HL7 outbound, portal form submits).
  • The task runs, criterion runs, and scored results.

​
Creating a Playground

# Create the playground
curl -X POST https://api.verial.ai/playgrounds \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment_id": "'"$ENVIRONMENT_ID"'"}'
# → save the returned id as $PLAYGROUND_ID

# Fetch full details including each sandbox's credentials
curl "https://api.verial.ai/playgrounds/$PLAYGROUND_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Do your work against the sandbox credentials returned above...

# Release resources when finished
curl -X POST "https://api.verial.ai/playgrounds/$PLAYGROUND_ID/teardown" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

​
Next Steps

Sandboxes

The running simulator instances inside a playground.

Playgrounds API

REST endpoints and full object reference.