Runtime API
The Runtime's HTTP routes, protocol headers, and readiness checks.
Most apps use the SDK
The Agents SDK client wraps these routes, headers, and compatibility checks. Generated per-endpoint pages are coming.
Compatibility and readiness
GET /health is unauthenticated and reports Runtime version, Host id, protocol
range, and required features:
{
"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
| 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(). |
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
| 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
| 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
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.