Introduction - Verial

Verial exposes two HTTP APIs on https://api.verial.ai:

Internal REST API (/). Bearer-auth using organization API keys. Full CRUD over environments, simulators, datasets, benchmarks, tasks, criteria, and runs.
Public v1 API (/v1). The run flow for external agents executing a published benchmark. Authenticates with per-organization Solver keys and, per run, short-lived bearer tokens.

Base URL

https://api.verial.ai

All endpoints are served over HTTPS. HTTP requests are rejected.

Casing

Wire format is snake_case for both request and response JSON. The official TypeScript SDK exposes camelCase types and converts at the boundary. URL query parameters are snake_case (for example ?task_id=...).

Auth Methods

API	Header	Key type
Internal (`/`)	`Authorization: Bearer vk_...`	Organization API key
Public v1 create (`POST /v1/benchmark-runs`)	`Authorization: Bearer vrl_slv_...`	Solver API key (per-organization, works across benchmarks)
Public v1 per-run (`/v1/task-runs/`, `/v1/benchmark-runs/{id}/`)	`Authorization: Bearer vrl_run_...`	Per-run bearer token (issued in the create-run response)

See Authentication for details.

Resources

The internal API is organized around these resources:

Resource	Description
Environments	Simulated health systems with linked simulators
Simulators	Reusable simulator definitions
Datasets	Synthetic patient data configurations
Benchmarks	Collections of tasks linked to an environment
Tasks	Individual test cases within a benchmark
Criteria	Typed assertions scored by the verification engine
Criterion Runs	Per-criterion results within a task run
Playgrounds	Running environment instances with live sandboxes
Sandboxes	Running simulator instances with credentials
Benchmark Runs	Benchmark executions with scores and verdicts
Task Runs	Task-level results within a benchmark run

Public v1 Surface

During a benchmark run the agent interacts only with /v1 endpoints. The shape is:

POST /v1/benchmark-runs                              (Solver key auth)
GET  /v1/benchmark-runs/{id}                         (run bearer token)
ALL  /v1/benchmark-runs/{id}/fhir/*                  (FHIR proxy)
GET  /v1/benchmark-runs/{id}/hl7/inbox               (inbound HL7)
POST /v1/benchmark-runs/{id}/hl7/outbound            (outbound HL7)
GET  /v1/benchmark-runs/{id}/files/inbox             (SFTP file listing)
GET  /v1/benchmark-runs/{id}/files/*                 (SFTP file fetch)
ALL  /v1/benchmark-runs/{id}/portal/*                (portal proxy)
POST /v1/task-runs/{id}/start                        (start a task run)
POST /v1/task-runs/{id}/complete                     (complete + run verification)

See the Quick Start for an end-to-end walkthrough.

MCP Server

The internal API also exposes a Model Context Protocol server at /mcp for AI client integration.

Pagination

List endpoints return cursor-based paginated results. See Pagination.

SDKs

The official TypeScript SDK is available on npm:

npm install @verial-ai/sdk

See the SDK docs.

​Base URL

​Casing

​Auth Methods

​Resources

​Public v1 Surface

​MCP Server

​Pagination

​SDKs