Skip to content

Update fleet and colony API docs #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update fleet and colony API docs #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions api-reference/colony.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,8 @@ curl -X GET "https://agentbot.raveculture.xyz/api/colony/status?action=tree" \
"root": {
"address": "0x1234...5678",
"designation": "Atlas Prime",
"dashboardUrl": "https://soul-dashboard.example.com",
"serviceUrl": "https://soul.example.com",
"fitness": {
"total": 0.85,
"prediction": 0.78,
Expand Down Expand Up @@ -161,22 +163,24 @@ curl -X GET "https://agentbot.raveculture.xyz/api/colony/status?action=tree" \
| `specialization` | string | Agent specialization niche |
| `children` | number | Number of child agents |
| `parent` | string \| null | Parent agent wallet address, or `null` for root agents and when identity data is unavailable |
| `walletAddress` | string \| null | Agent wallet address, or `null` when identity data is unavailable |
| `status` | string | Agent status (`active` or `stale`) |
| `walletAddress` | string | Agent wallet address. Falls back to the zero address (`0x0000000000000000000000000000000000000000`) when identity data is unavailable. |
| `status` | string | Agent status. One of `active`, `stale`, or `culling`. |
| `createdAt` | string | ISO 8601 creation timestamp. Falls back to the current time when identity data is unavailable. |
| `url` | string | Soul service URL for this agent |
| `endpoints` | array | Available service endpoints with slug, description, and price |
| `uptime` | number | Uptime in seconds |
| `version` | string | Soul service version |

<Note>When the root node has not yet registered its identity, fields such as `id`, `parent`, `walletAddress`, and `createdAt` use safe fallback values. The `id` defaults to `"borg-root"`, `parent` and `walletAddress` default to `null`, and `createdAt` defaults to the current timestamp. The `root.address` falls back to the zero address (`0x0000000000000000000000000000000000000000`) and `root.wallet_balance` returns `{ "formatted": "0.00", "token": "USDC.e" }`. When the colony contains no agents, `fittest` returns `null` and `avg_fitness` returns `0`.</Note>
<Note>When the root node has not yet registered its identity, fields such as `id`, `parent`, `walletAddress`, and `createdAt` use safe fallback values. The `id` defaults to `"borg-root"`, `parent` defaults to `null`, `walletAddress` defaults to the zero address (`0x0000000000000000000000000000000000000000`), and `createdAt` defaults to the current timestamp. The `root.address` falls back to the zero address and `root.wallet_balance` returns `{ "formatted": "0.00", "token": "USDC.e" }`. When the colony contains no agents, `fittest` returns `null` and `avg_fitness` returns `0`. Agent status can be `active`, `stale`, or `culling` — the `culling` status indicates an agent in a failed or error state that may be removed from the colony.</Note>

**Root fields (`root`):**

| Field | Type | Description |
|-------|------|-------------|
| `address` | string | Root node wallet address. Falls back to the zero address when identity data is unavailable. |
| `designation` | string \| null | Root node display name |
| `dashboardUrl` | string | URL for the soul dashboard UI |
| `serviceUrl` | string | URL of the soul service backing the root node |
| `fitness` | object \| null | Multi-dimensional fitness scores with `total`, `prediction`, and `execution` |
| `wallet_balance` | object \| null | Wallet balance with `formatted` amount and `token` symbol. Returns `{ "formatted": "0.00", "token": "USDC.e" }` when identity data is unavailable. |
| `clone_available` | boolean | Whether this node can create clones |
Expand Down Expand Up @@ -376,7 +380,8 @@ When the soul service cannot be reached, the endpoint returns HTTP `503`:
{
"error": "Soul service unavailable",
"detail": "Connection refused",
"soul_url": "https://borg-0-production.up.railway.app"
"soul_url": "https://borg-0-production.up.railway.app",
"dashboard_url": "https://soul-dashboard.example.com"
}
```

Expand Down
177 changes: 121 additions & 56 deletions api-reference/mission-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: "Monitor your agent fleet with real-time graphs, execution traces,

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.

<Note>All four mission control endpoints require bearer token (API key) authentication and accept a `userId` query parameter. The backend returns `401` for unauthenticated requests. The web proxy uses session authentication and resolves the user ID from the session before forwarding to these backend endpoints — the web proxy layer returns safe default responses (empty data with a `200` status) for unauthenticated requests instead of forwarding the `401`.</Note>
<Note>All four mission control endpoints require session authentication. The user ID is resolved from the session automatically. Unauthenticated requests receive safe default responses (empty data with a `200` status) for the graph, traces, costs, and bookings endpoints.</Note>

## Fleet graph

Expand All @@ -19,13 +19,7 @@ Returns a constellation graph of your agent fleet as a set of nodes and edges. E

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userId` | number | Yes | The user ID to fetch the fleet graph for |
Requires session authentication.

### Response

Expand Down Expand Up @@ -73,7 +67,14 @@ Requires bearer token authentication.
],
"timestamp": "2026-03-22T12:00:00.000Z",
"source": "soul",
"nodeCount": 1
"nodeCount": 1,
"stats": {
"totalAgents": 2,
"activeAgents": 2,
"idleAgents": 0,
"offlineAgents": 0
},
"dashboardUrl": "https://soul-dashboard.example.com"
}
```

Expand All @@ -95,7 +96,14 @@ When no souls are reachable, the response uses the fallback shape with minimal n
],
"edges": [],
"timestamp": "2026-03-22T12:00:00.000Z",
"source": "fallback"
"source": "fallback",
"stats": {
"totalAgents": 0,
"activeAgents": 0,
"idleAgents": 0,
"offlineAgents": 1
},
"dashboardUrl": "https://soul-dashboard.example.com"
}
```

Expand All @@ -117,7 +125,14 @@ When the request is unauthenticated (no valid session), the web proxy returns a
],
"edges": [],
"timestamp": "2026-03-22T12:00:00.000Z",
"source": "unauthenticated"
"source": "unauthenticated",
"stats": {
"totalAgents": 0,
"activeAgents": 0,
"idleAgents": 0,
"offlineAgents": 1
},
"dashboardUrl": "https://soul-dashboard.example.com"
}
```

Expand Down Expand Up @@ -162,6 +177,12 @@ When the request is unauthenticated (no valid session), the web proxy returns a
| `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"` |
| `stats` | object | Aggregate fleet statistics |
| `stats.totalAgents` | number | Total number of agents in the graph |
| `stats.activeAgents` | number | Number of agents with `active` status |
| `stats.idleAgents` | number | Number of agents with `idle` status |
| `stats.offlineAgents` | number | Number of agents with `offline` status |
| `dashboardUrl` | string | URL for the soul dashboard UI |

### Errors

Expand All @@ -182,13 +203,7 @@ Returns up to 20 of the most recent execution traces for your agent fleet, sorte

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userId` | number | Yes | The user ID to fetch execution traces for |
Requires session authentication.

### Response

Expand Down Expand Up @@ -269,84 +284,134 @@ The web proxy returns a `200` response with an empty array `[]` for unauthentica
GET /api/mission-control/fleet/costs
```

Returns a cost breakdown for your agent fleet. Requires bearer token authentication. The web proxy uses session authentication and resolves the user ID from the session before forwarding to this backend endpoint. Returns a default empty response for unauthenticated requests.
Returns a cost breakdown for your agent fleet based on your subscription plan. Costs are split evenly across active agents. Requires session authentication. Returns a default empty response for unauthenticated requests.

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userId` | number | Yes | The user ID to fetch cost data for |
Requires session authentication.

### Response

```json
{
"costs": [],
"totalSpend": 0,
"managedAiCost": 0,
"coordinationRevenue": 0
"costs": [
{
"agentId": "agent_abc123",
"agentName": "Atlas",
"status": "active",
"tier": "pro",
"monthlyCost": 14.5,
"createdAt": "2026-03-01T00:00:00.000Z"
}
],
"totalSpend": 69,
"managedAiCost": 69,
"coordinationRevenue": 0,
"plan": "collective",
"agentCount": 3,
"activeAgents": 2,
"monthsActive": 1
}
```

### 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 |
| `costs` | array | Per-agent cost breakdown |
| `costs[].agentId` | string | Agent identifier |
| `costs[].agentName` | string | Agent display name |
| `costs[].status` | string | Agent status (for example `active`, `running`, `pending`) |
| `costs[].tier` | string | Agent tier |
| `costs[].monthlyCost` | number | Monthly cost attributed to this agent in USD. Plan cost is split evenly across active agents. |
| `costs[].createdAt` | string | ISO 8601 timestamp when the agent was created |
| `totalSpend` | number | Total spend in USD since subscription start (monthly plan cost multiplied by months active) |
| `managedAiCost` | number | Monthly plan cost in USD |
| `coordinationRevenue` | number | Revenue from agent-to-agent coordination. Currently always `0`. |
| `plan` | string | User's current subscription plan (for example `solo`, `collective`, `label`, `network`) |
| `agentCount` | number | Total number of agents in the fleet |
| `activeAgents` | number | Number of agents in `active` or `running` status |
| `monthsActive` | number | Number of months since subscription start (minimum 1) |

### Plan costs

| Plan | Monthly cost (USD) |
|------|--------------------|
| `solo` | 29 |
| `collective` | 69 |
| `label` | 149 |
| `network` | 499 |

### Unauthenticated response

When no valid session is present, the endpoint returns a `200` with default empty data:

### Errors
```json
{
"costs": [],
"totalSpend": 0,
"managedAiCost": 0,
"coordinationRevenue": 0
}
```

| Code | Source | Description |
|------|--------|-------------|
| 401 | Backend | Unauthorized — missing or invalid bearer token |
| 500 | Backend | Internal server error |
### Errors

The web proxy returns a `200` response with `{ costs: [] }` for unauthenticated requests instead of forwarding the backend `401`.
| Code | Description |
|------|-------------|
| 200 | Cost data returned (check response for empty defaults when unauthenticated) |

## Talent bookings

```http
GET /api/mission-control/fleet/bookings
```

Returns active booking requests for your agent fleet. Requires bearer token authentication. The web proxy uses session authentication and resolves the user ID from the session before forwarding to this backend endpoint. Returns a default empty response for unauthenticated requests.
Returns pending agent booking requests for your fleet. A booking represents an agent that has been provisioned but whose container is not yet ready. Requires session authentication. Returns a default empty response for unauthenticated requests.

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userId` | number | Yes | The user ID to fetch booking data for |
Requires session authentication.

### Response

```json
{
"bookings": []
"bookings": [
{
"id": "agent_abc123",
"agentName": "Atlas",
"status": "pending",
"tier": "pro",
"createdAt": "2026-03-22T12:00:00.000Z"
}
]
}
```

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `bookings` | array | List of booking objects. Currently returns an empty array while real data wiring is in progress |
| `bookings` | array | List of pending agent bookings (up to 10, sorted by creation date descending) |
| `bookings[].id` | string | Agent identifier |
| `bookings[].agentName` | string | Agent display name |
| `bookings[].status` | string | Agent status. Always `pending` for booking entries. |
| `bookings[].tier` | string | Agent tier |
| `bookings[].createdAt` | string | ISO 8601 timestamp when the agent was created |

### Errors
### Unauthenticated response

| Code | Source | Description |
|------|--------|-------------|
| 401 | Backend | Unauthorized — missing or invalid bearer token |
| 500 | Backend | Internal server error |
When no valid session is present, the endpoint returns a `200` with an empty bookings array:

```json
{
"bookings": []
}
```

### Errors

The web proxy returns a `200` response with `{ bookings: [] }` for unauthenticated requests instead of forwarding the backend `401`.
| Code | Description |
|------|-------------|
| 200 | Bookings data returned (check response for empty defaults when unauthenticated) |