Skip to main content

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.

Verial exposes two HTTP APIs on https://api.verial.ai:
  1. Internal REST API (/). Bearer-auth using organization API keys. Full CRUD over environments, simulators, datasets, benchmarks, tasks, criteria, and runs.
  2. 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

APIHeaderKey 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:
ResourceDescription
EnvironmentsSimulated health systems with linked simulators
SimulatorsReusable simulator definitions
DatasetsSynthetic patient data configurations
BenchmarksCollections of tasks linked to an environment
TasksIndividual test cases within a benchmark
CriteriaTyped assertions scored by the verification engine
Criterion RunsPer-criterion results within a task run
PlaygroundsRunning environment instances with live sandboxes
SandboxesRunning simulator instances with credentials
Benchmark RunsBenchmark executions with scores and verdicts
Task RunsTask-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.