diff --git a/api-reference/colony.mdx b/api-reference/colony.mdx index 7c5cb17..c80e71a 100644 --- a/api-reference/colony.mdx +++ b/api-reference/colony.mdx @@ -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, @@ -161,15 +163,15 @@ 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 | -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`. +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. **Root fields (`root`):** @@ -177,6 +179,8 @@ curl -X GET "https://agentbot.raveculture.xyz/api/colony/status?action=tree" \ |-------|------|-------------| | `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 | @@ -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" } ``` diff --git a/api-reference/mission-control.mdx b/api-reference/mission-control.mdx index 4eb6c69..751726d 100644 --- a/api-reference/mission-control.mdx +++ b/api-reference/mission-control.mdx @@ -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. -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`. +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. ## Fleet graph @@ -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 @@ -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" } ``` @@ -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" } ``` @@ -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" } ``` @@ -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 @@ -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 @@ -269,26 +284,33 @@ 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 } ``` @@ -296,19 +318,48 @@ Requires bearer token authentication. | 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 @@ -316,23 +367,25 @@ The web proxy returns a `200` response with `{ costs: [] }` for unauthenticated 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" + } + ] } ``` @@ -340,13 +393,25 @@ Requires bearer token authentication. | 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) |