Surfaces and endpoints#
The operator surfaces, the endpoints that sit outside operator authentication, and what each one is for.
Operator surfaces#
| Surface | Path | Purpose |
|---|---|---|
| Director | / |
The world Now surface and the operator's working area |
| Agents | /agents |
Resident configuration |
| Worlds | /worlds |
World identity and lifecycle |
| Runs | /runs |
Run list and run detail |
| Scenarios | /scenarios |
Scenario definitions |
| Environments | /environments |
Environment definitions |
| Range Control | /range-control |
Range operations |
| Evaluations | /evaluations |
Paired evaluation viewer |
| Settings | /settings |
Provider settings |
| Observer | /observe |
Reduced read-only view |
| World Lens | /lens |
Live schematic |
When BLACKBOX_OPERATOR_TOKEN is set, Director pages and application APIs
require it.
Endpoints outside the operator token#
Three surfaces keep their own separate behaviour and are not covered by the operator token:
| Endpoint | Behaviour |
|---|---|
| Observer share links | Carry their own token |
/api/mcp |
Its own token behaviour, for MCP-connected clients |
/api/health, /api/ready |
Public |
Setting an operator token does not close /api/health or
/api/ready. If the service is reachable from a network you do not control,
those endpoints are reachable too.
Health and readiness#
| Endpoint | Answers |
|---|---|
/api/health |
Whether the process is alive |
/api/ready |
Whether it is ready to serve |
Use readiness, not health, to decide whether to send traffic.
Application API shape#
The application exposes a broad REST surface — roughly one hundred routes — covering agents, runs, worlds, scenarios, environments, identities, organisations, permissions, audit, injects, provider settings, and the fictional communication and network surfaces inside Ridgeport (email, SMS, social, web, networks with subnets, hosts, DNS and firewall).
World-scoped routes appear in two forms: a singular /api/world/... form for
the server's one world, and an /api/worlds/{id}/... form. Both address world
state; the singular form is the ordinary path for a single-world service.
Legacy compatibility surfaces#
Legacy Scenario types and routes remain as measured compatibility surfaces under the canonical World Program and Event Arc domain. They are retained deliberately and measured rather than removed. Prefer the canonical routes for new work.
Verify#
curl -sS http://127.0.0.1:4287/api/readyA ready service responds without an operator token. A Director page request without the token is refused when a token is configured.