> ## 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.

# Introduction

> The Verial API. Healthcare simulated environment platform for defining environments, publishing benchmarks, and running scored rollouts.

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

| 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](/api-reference/authentication) for details.

## Resources

The internal API is organized around these resources:

| Resource                                                  | Description                                        |
| --------------------------------------------------------- | -------------------------------------------------- |
| [Environments](/api-reference/resources/environments)     | Simulated health systems with linked simulators    |
| [Simulators](/api-reference/resources/simulators)         | Reusable simulator definitions                     |
| [Datasets](/api-reference/resources/datasets)             | Synthetic patient data configurations              |
| [Benchmarks](/api-reference/resources/benchmarks)         | Collections of tasks linked to an environment      |
| [Tasks](/api-reference/resources/tasks)                   | Individual test cases within a benchmark           |
| [Criteria](/api-reference/resources/criteria)             | Typed assertions scored by the verification engine |
| [Criterion Runs](/api-reference/resources/criterion-runs) | Per-criterion results within a task run            |
| [Playgrounds](/api-reference/resources/playgrounds)       | Running environment instances with live sandboxes  |
| [Sandboxes](/api-reference/resources/sandboxes)           | Running simulator instances with credentials       |
| [Benchmark Runs](/api-reference/resources/runs)           | Benchmark executions with scores and verdicts      |
| [Task Runs](/api-reference/resources/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](/guides/quickstart) for an end-to-end walkthrough.

## MCP Server

The internal API also exposes a [Model Context Protocol](/mcp/overview) server at `/mcp` for AI client integration.

## Pagination

List endpoints return cursor-based paginated results. See [Pagination](/api-reference/pagination).

## SDKs

The official TypeScript SDK is available on npm:

```bash theme={null}
npm install @verial-ai/sdk
```

See the [SDK docs](/sdk/installation).