> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-spec-sync-1774445910.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Mission control API
> Monitor your agent fleet with real-time graphs, execution traces, cost attribution, and booking data
# Mission control API
Mission control provides a real-time view of your agent fleet. Use these endpoints to visualize agent relationships, trace execution activity, attribute costs per agent, and track talent bookings.
All mission control endpoints require bearer token (API key) authentication. The fleet graph and traces endpoints also require a `userId` query parameter. The web proxy uses session authentication and resolves the user ID from the session before forwarding to these endpoints. The fleet graph and traces endpoints return safe default responses for unauthenticated requests instead of an error.
## Fleet graph
```http theme={null}
GET /api/mission-control/fleet/graph
```
Returns a constellation graph of your agent fleet as a set of nodes and edges. Each node represents an agent with a `role` and positional data for graph layout. Edges use `from`/`to` fields with a `strength` value indicating relationship weight.
### Authentication
Requires bearer token authentication.
### Query parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------- |
| `userId` | number | Yes | The user ID to fetch the fleet graph for |
### Response
```json theme={null}
{
"nodes": [
{
"id": "borg-0",
"name": "borg-0",
"role": "orchestrator",
"status": "active",
"x": 400,
"y": 300,
"load": 72,
"memory": 58,
"fitness": 85,
"walletAddress": "0x1234...abcd",
"children": 2,
"endpoints": 3,
"cycles": 1042,
"regime": "explore",
"freeEnergy": 0.34,
"url": "https://borg-0-production.up.railway.app"
},
{
"id": "a1b2c3d4",
"name": "Clone-a1b2c3d4",
"role": "worker",
"status": "active",
"x": 200,
"y": 450,
"load": 30,
"memory": 20,
"fitness": 40,
"walletAddress": "0xabcd...1234"
}
],
"edges": [
{
"id": "e-borg-0-a1b2c3d4",
"from": "borg-0",
"to": "a1b2c3d4",
"strength": 0.6
}
],
"timestamp": "2026-03-22T12:00:00.000Z",
"source": "soul",
"nodeCount": 1
}
```
When no souls are reachable, the response uses the fallback shape with minimal node data:
```json theme={null}
{
"nodes": [
{
"id": "atlas",
"name": "Atlas",
"role": "orchestrator",
"status": "offline",
"x": 400,
"y": 300,
"load": 0,
"memory": 0
}
],
"edges": [],
"timestamp": "2026-03-22T12:00:00.000Z",
"source": "fallback"
}
```
When the request is unauthenticated (no valid session), the endpoint returns a default response instead of an error:
```json theme={null}
{
"nodes": [
{
"id": "atlas",
"name": "Atlas",
"role": "orchestrator",
"status": "offline",
"x": 400,
"y": 300,
"load": 0,
"memory": 0
}
],
"edges": [],
"timestamp": "2026-03-22T12:00:00.000Z",
"source": "unauthenticated"
}
```
### Node object
| Field | Type | Description |
| --------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `id` | string | Unique agent identifier (designation or truncated instance ID for clones) |
| `name` | string | Agent display name |
| `role` | string | Agent role. One of `orchestrator`, `specialist`, or `worker` |
| `status` | string | Current status. One of `active`, `idle`, `stale`, or `offline` (fallback only) |
| `x` | number | Horizontal position for graph layout |
| `y` | number | Vertical position for graph layout |
| `load` | number | Current load percentage (0–100). Derived from active plan progress |
| `memory` | number | Memory usage percentage (0–100). Derived from cortex experience count |
| `fitness` | number | Fitness score (0–100). Only present on live nodes |
| `walletAddress` | string | On-chain wallet address of the agent. Present when available |
| `children` | number | Number of child (clone) instances. Only present on parent nodes |
| `endpoints` | number | Number of registered endpoints. Only present on parent nodes |
| `cycles` | number | Total cognitive cycles completed. Only present on parent nodes |
| `regime` | string | Current free energy regime (for example `"explore"` or `"exploit"`). Only present on parent nodes |
| `freeEnergy` | number | Current free energy value. Only present on parent nodes |
| `url` | string | Soul instance URL. Only present on parent nodes |
The `type` field was renamed to `role` and now uses the values `orchestrator`, `specialist`, and `worker`. The `monitor` role is no longer returned by this endpoint.
### Edge object
| Field | Type | Description |
| ---------- | ------ | ----------------------------------- |
| `id` | string | Unique edge identifier |
| `from` | string | Source agent ID |
| `to` | string | Target agent ID |
| `strength` | number | Relationship weight between 0 and 1 |
The `source` and `target` fields were renamed to `from` and `to`. The `type` field on edges was replaced by `strength`.
### Response metadata
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp` | string | ISO 8601 timestamp of the response |
| `source` | string | Data source. `"soul"` for live data, `"fallback"` when no souls are reachable, `"unauthenticated"` when no valid session is present |
| `nodeCount` | number | Number of live soul nodes fetched. Only present when `source` is `"soul"` |
### Errors
Unauthenticated requests return a `200` response with default empty data (see above) instead of an error.
## Execution traces
```http theme={null}
GET /api/mission-control/fleet/traces
```
Returns up to 20 of the most recent execution traces for your agent fleet, sorted by recency. Traces include active plan steps, recent thoughts, free energy component readings, and cycle status from live soul instances. Returns an empty array when no soul instances are reachable or when the request is unauthenticated.
### Authentication
Requires bearer token authentication.
### Query parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------- |
| `userId` | number | Yes | The user ID to fetch execution traces for |
### Response
```json theme={null}
[
{
"id": "trace-plan-0",
"type": "plan",
"label": "plan: reflect (2/5)",
"agent": "borg-0",
"status": "running",
"duration": "—",
"startedAt": "2026-03-22T12:00:00.000Z",
"tokens": null
},
{
"id": "trace-thought-0-0",
"type": "inference",
"label": "plan: next step is to consolidate memory entries",
"agent": "borg-0",
"status": "success",
"duration": "285ms",
"startedAt": "2026-03-22T11:59:56.000Z",
"tokens": 542
},
{
"id": "trace-fe-0-0",
"type": "monitor",
"label": "cortex: surprise=0.12, contribution=0.04",
"agent": "borg-0",
"status": "success",
"duration": "1ms",
"startedAt": "2026-03-22T11:59:50.000Z",
"tokens": null
},
{
"id": "trace-cycles-0",
"type": "monitor",
"label": "cycle 1042 complete — mode: active, regime: explore",
"agent": "borg-0",
"status": "success",
"duration": "—",
"startedAt": "2026-03-22T11:59:45.000Z",
"tokens": null
}
]
```
### Trace object
| Field | Type | Description |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------ |
| `id` | string | Unique trace identifier |
| `type` | string | Task type. One of `plan`, `tool_call`, `inference`, or `monitor` |
| `label` | string | Description of the task executed |
| `agent` | string | Soul designation that produced the trace (for example `"borg-0"`) |
| `status` | string | Execution result. One of `success`, `running`, or `idle` |
| `duration` | string | Execution time in milliseconds (for example `"285ms"`), or `"—"` for ongoing or non-timed traces |
| `startedAt` | string | ISO 8601 timestamp when the task started |
| `tokens` | number \| null | Token count for inference-type traces. `null` for other trace types |
The response is capped at 20 traces, sorted from most recent to oldest.
### Errors
Unauthenticated requests return a `200` response with an empty array `[]` instead of an error.
## Cost attribution
```http theme={null}
GET /api/mission-control/fleet/costs
```
Returns a cost breakdown for your agent fleet. Uses session authentication — the user is resolved from the active session. Returns a default empty response for unauthenticated requests.
### Authentication
Requires session authentication.
### Response
```json theme={null}
{
"costs": [],
"totalSpend": 0,
"managedAiCost": 0,
"coordinationRevenue": 0
}
```
### Response fields
| Field | Type | Description |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `costs` | array | List of cost line items. Currently returns an empty array while real data wiring is in progress |
| `totalSpend` | number | Total spend across the fleet |
| `managedAiCost` | number | AI model usage cost |
| `coordinationRevenue` | number | Revenue from agent coordination |
### Errors
Unauthenticated requests return a `200` response with `{ costs: [] }` instead of an error.
## Talent bookings
```http theme={null}
GET /api/mission-control/fleet/bookings
```
Returns active booking requests for your agent fleet. Uses session authentication — the user is resolved from the active session. Returns a default empty response for unauthenticated requests.
### Authentication
Requires session authentication.
### Response
```json theme={null}
{
"bookings": []
}
```
### Response fields
| Field | Type | Description |
| ---------- | ----- | ----------------------------------------------------------------------------------------------- |
| `bookings` | array | List of booking objects. Currently returns an empty array while real data wiring is in progress |
### Errors
Unauthenticated requests return a `200` response with `{ bookings: [] }` instead of an error.