# Runtime API (/docs/reference/runtime-api)



<div className="api-package">
  @nylorun/runtime 0.11 · protocol 2
</div>

<Callout title="Most apps use the SDK">
  The [Agents SDK client](/docs/reference/agents/client) wraps these routes,
  headers, and compatibility checks. Generated per-endpoint pages are coming.
</Callout>

## Compatibility and readiness [#compatibility-and-readiness]

`GET /health` is unauthenticated and reports Runtime version, Host id, protocol
range, and required features:

```json
{
  "status": "ok",
  "service": "nylorun-runtime",
  "version": "0.11.0-beta",
  "protocol": {
    "min": 2,
    "max": 2,
    "features": ["runtime-tenants", "admin-status", "studio-principal"]
  }
}
```

Hosts may also advertise optional `tenant-fixture-model`. `GET /ready` checks
Postgres, Restate, and S2 and returns `503` with dependency checks until all
required services are available.

## Headers [#headers]

| Header             | Sent on                | Value                                                                     |
| ------------------ | ---------------------- | ------------------------------------------------------------------------- |
| `Authorization`    | Every request          | `Bearer <key>`                                                            |
| `Nylorun-Protocol` | Every request          | `2`                                                                       |
| `Nylorun-Tenant`   | Tenant requests        | The Tenant id. Admin requests omit it.                                    |
| `Nylorun-Subject`  | App-server requests    | The person the call is for. See [as()](/docs/reference/agents/client#as). |
| `Nylorun-Scopes`   | With `Nylorun-Subject` | Space-separated scopes, e.g. `sessions:own`.                              |

Subject headers require the optional feature `subject-headers`. Only an
application key may send them. The Runtime refuses browser requests that carry
`Origin`.

## Host routes [#host-routes]

| Method       | Path                      | Purpose                                                          |
| ------------ | ------------------------- | ---------------------------------------------------------------- |
| `GET`        | `/health`                 | Liveness and compatibility.                                      |
| `GET`        | `/ready`                  | Postgres, Restate, and S2 readiness.                             |
| `GET`        | `/v1/admin/status`        | Host and Tenant aggregate status.                                |
| `GET/POST`   | `/v1/admin/tenants`       | List or create Tenants. Creation accepts `studioCredentialHash`. |
| `GET/DELETE` | `/v1/admin/tenants/:id`   | Inspect or delete a Tenant.                                      |
| `POST`       | `/v1/admin/host/shutdown` | Host-private shutdown route.                                     |

Application principal id `studio` is reserved. `PUT /v1/tenant/config/seed`
accepts `fixtureModel: true` when `tenant-fixture-model` is available.

## Tenant routes [#tenant-routes]

| Method           | Path                               | Purpose                                                                 |
| ---------------- | ---------------------------------- | ----------------------------------------------------------------------- |
| `GET`            | `/v1/tenant`                       | Tenant status; `checks.store`, plus optional `execution` and `streams`. |
| `PUT/GET`        | `/v1/agents/:id`, `/v1/agents`     | Save or list definitions.                                               |
| `PUT/GET`        | `/v1/sessions/:id`, `/v1/sessions` | Create, inspect, or list sessions.                                      |
| `POST`           | `/v1/sessions/:id/commands`        | Input, approval, response, cancellation, or executor result.            |
| `GET`            | `/v1/sessions/:id/items`           | Canonical history.                                                      |
| `GET`            | `/v1/sessions/:id/events`          | Canonical SSE history.                                                  |
| CRUD             | `/v1/vaults/*`                     | End-user vaults and credentials.                                        |
| `GET/PUT`        | `/v1/tenant/model*`                | Model credentials, selection, and catalog.                              |
| `GET`            | `/v1/tenant/sandbox`               | Virtual sandbox status.                                                 |
| `PUT/GET/DELETE` | `/v1/executors*`                   | Executor registration and administration.                               |

Executor routes provide SSE discovery, action listing, claims, heartbeats, and
`action_result` commands. Executor credentials are scoped to one runnable and
cannot call vault, model, definition-management, or Admin routes.

## Ephemeral embedding [#ephemeral-embedding]

`startEphemeralRuntime()` creates an in-memory Host and Tenant for tests and
controlled embedding. Nothing survives `close()`; use the Docker stack for
durable work.

Authoritative implementation details are in the
[Runtime source](https://github.com/nylorun/agents/tree/main/runtime).