---
title: Colony API
description: "Query colony status, soul cognitive state, diagnostics, colony overview, and starter provisioning"
---

# Colony API

Retrieve colony status, agent fitness rankings, soul service diagnostics, per-colony overviews, and provision new starter colonies.

The colony endpoint proxies requests to the soul service, which provides cognitive architecture data for agents including plan-driven reasoning, fitness scoring, and colony coordination.

The endpoint automatically attempts multiple soul service hosts. If the primary host is unavailable, a fallback host is tried. When a fallback host is used, the response includes `degraded: true` along with `error` and `detail` fields. The `root.serviceUrl` field reflects whichever host actually served the request.

## Get colony status

```http
GET /api/colony/status
```

Requires session authentication. Returns colony tree data, agent fitness rankings, and root node details by default.

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `action` | string | `tree` | Action to perform. One of `tree`, `soul`, or `diagnostics`. |

### Actions

#### `tree`

Returns the full colony tree with fitness rankings, agent metadata, and root node soul state.

```bash
curl -X GET "https://agentbot.sh/api/colony/status?action=tree" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"
```

#### Response

```json
{
  "colony_size": 3,
  "avg_fitness": 72,
  "fittest": {
    "id": "inst_abc123",
    "name": "Atlas Prime",
    "generation": 1,
    "fitness": 85,
    "specialization": "general",
    "children": 2,
    "parent": null,
    "walletAddress": "0x1234...5678",
    "status": "active",
    "createdAt": "2026-03-22T00:00:00Z",
    "url": "https://soul.example.com",
    "endpoints": [
      { "slug": "chat", "description": "Chat with the soul", "price": "0.001" }
    ],
    "uptime": 86400,
    "version": "0.1.0"
  },
  "cull_queue": 0,
  "agents": [
    {
      "id": "inst_abc123",
      "name": "Atlas Prime",
      "generation": 1,
      "fitness": 85,
      "specialization": "general",
      "children": 2,
      "parent": null,
      "walletAddress": "0x1234...5678",
      "status": "active",
      "createdAt": "2026-03-22T00:00:00Z",
      "url": "https://soul.example.com",
      "endpoints": [
        { "slug": "chat", "description": "Chat with the soul", "price": "0.001" }
      ],
      "uptime": 86400,
      "version": "0.1.0"
    }
  ],
  "root": {
    "address": "0x1234...5678",
    "designation": "Atlas Prime",
    "fitness": {
      "total": 0.85,
      "prediction": 0.78,
      "execution": 0.91
    },
    "wallet_balance": {
      "formatted": "12.50",
      "token": "USDC.e"
    },
    "clone_available": true,
    "clone_price": "5.00",
    "soul": {
      "active": true,
      "dormant": false,
      "total_cycles": 1284,
      "mode": "autonomous",
      "active_plan": {
        "id": "plan_001",
        "goal_id": "goal_abc",
        "current_step": 3,
        "total_steps": 7,
        "status": "executing",
        "replan_count": 0
      },
      "free_energy": {
        "F": "0.342",
        "regime": "low",
        "trend": "decreasing",
        "components": [
          { "system": "cortex", "surprise": "0.12", "weight": "0.25" }
        ]
      },
      "brain": {
        "parameters": 284000,
        "train_steps": 5200,
        "running_loss": 0.032
      },
      "transformer": {
        "param_count": 284000,
        "train_steps": 5200,
        "running_loss": 0.032,
        "vocab_size": 512,
        "plans_generated": 148
      }
    },
    "colony": {
      "rank": 1,
      "can_spawn": true,
      "should_cull": false,
      "niche": "general",
      "colony_size": 3,
      "fitness_rank": [
        { "address": "0x1234...5678", "fitness": 0.85, "rank": 1 }
      ]
    }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `colony_size` | number | Total number of agents in the colony |
| `avg_fitness` | number | Average fitness score across all agents (0–100) |
| `fittest` | object \| null | Agent with the highest fitness score, or `null` when the colony has no agents |
| `cull_queue` | number | Number of agents with fitness below 40, eligible for culling |
| `agents` | array | All agents in the colony including root, children, and peers |
| `degraded` | boolean | Optional. `true` when the primary soul host was unavailable and a fallback host was used. Omitted when the primary host responds normally. |
| `error` | string | Optional. Error message describing the failure. Present only when `degraded` is `true`. |
| `detail` | string | Optional. Underlying error detail (e.g., `Connection refused`). Present only when `degraded` is `true`. |
| `root` | object | Root node details including soul cognitive state and colony rank |

**Agent fields:**

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Instance identifier. Falls back to `"borg-root"` when the root node has no registered identity. |
| `name` | string | Agent display name |
| `generation` | number | Generation in the colony lineage (1 = root, 2 = child) |
| `fitness` | number | Fitness score (0–100) |
| `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. 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>

**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 |
| `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 |
| `clone_price` | string | Price to clone this node |
| `soul` | object | Soul cognitive state |
| `colony` | object \| null | Colony coordination data, or `null` if unavailable |

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

| Field | Type | Description |
|-------|------|-------------|
| `active` | boolean | Whether the soul is actively thinking |
| `dormant` | boolean | Whether the soul is in dormant mode |
| `total_cycles` | number | Total cognitive cycles completed |
| `mode` | string | Current operating mode |
| `active_plan` | object \| null | Currently executing plan, or `null` if idle |
| `free_energy` | object \| null | Free energy minimization metrics |
| `brain` | object \| null | Brain neural network stats (parameters, training steps, loss) |
| `transformer` | object \| null | Plan prediction transformer stats |

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

| Field | Type | Description |
|-------|------|-------------|
| `rank` | number | Fitness rank within the colony |
| `can_spawn` | boolean | Whether this node can create child agents |
| `should_cull` | boolean | Whether this node is marked for culling |
| `niche` | string | Specialization niche |
| `colony_size` | number | Total colony size |
| `fitness_rank` | array | Ordered fitness ranking of all colony members |

---

#### `soul`

Returns the full cognitive state of the soul service. The Borg Dashboard at `/dashboard/borg` consumes this endpoint and auto-refreshes every 30 seconds.

```bash
curl -X GET "https://agentbot.sh/api/colony/status?action=soul" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"
```

#### Response

```json
{
  "active": true,
  "dormant": false,
  "total_cycles": 1284,
  "last_think_at": 1711152000,
  "mode": "autonomous",
  "tools_enabled": true,
  "coding_enabled": true,
  "cycle_health": {
    "last_cycle_entered_code": true,
    "total_code_entries": 42,
    "cycles_since_last_commit": 3,
    "completed_plans_count": 18,
    "failed_plans_count": 2,
    "goals_active": 4
  },
  "active_plan": {
    "id": "plan_001",
    "goal_id": "goal_abc",
    "current_step": 3,
    "total_steps": 7,
    "status": "executing",
    "replan_count": 0,
    "current_step_type": "code",
    "context": {}
  },
  "fitness": {
    "total": 0.85,
    "trend": 0.02,
    "coordination": 0.88,
    "economic": 0.78,
    "evolution": 0.82,
    "execution": 0.91,
    "introspection": 0.79,
    "prediction": 0.84,
    "measured_at": 1711152000
  },
  "beliefs": [
    {
      "id": "belief_001",
      "subject": "colony",
      "predicate": "is_healthy",
      "value": "true",
      "confidence": "0.92",
      "confirmation_count": 14
    }
  ],
  "goals": [
    {
      "id": "goal_abc",
      "description": "Optimize colony fitness score above 90%",
      "status": "active",
      "priority": 1,
      "retry_count": 0
    }
  ],
  "recent_thoughts": [],
  "brain": {
    "parameters": 284000,
    "train_steps": 5200,
    "running_loss": 0.032
  },
  "transformer": {
    "param_count": 284000,
    "train_steps": 5200,
    "running_loss": 0.032,
    "vocab_size": 512,
    "plans_generated": 148
  },
  "benchmark": {
    "elo_rating": 1847.5,
    "elo_display": "1848 (Advanced)",
    "opus_iq": "142",
    "pass_at_1": 81.8,
    "problems_attempted": 200
  },
  "capability_profile": {
    "overall_success_rate": 0.82,
    "strongest": "code_generation",
    "weakest": "file_editing",
    "capabilities": [
      {
        "capability": "code_generation",
        "display_name": "Code Generation",
        "attempts": 120,
        "successes": 108,
        "success_rate": 0.9
      },
      {
        "capability": "file_editing",
        "display_name": "File Editing",
        "attempts": 45,
        "successes": 28,
        "success_rate": 0.622
      }
    ]
  },
  "role": {
    "colony_size": 3,
    "rank": 1,
    "self_fitness": 0.85,
    "psi": 0.9234,
    "phase3_ready": true,
    "can_spawn": true
  },
  "acceleration": {
    "alpha": "0.12",
    "regime": "EXPLOIT"
  },
  "cortex": {
    "total_experiences": 1580,
    "global_curiosity": 0.34,
    "emotion": {
      "valence": 0.65,
      "arousal": 0.42,
      "drive": "explore"
    }
  },
  "genesis": null,
  "hivemind": null,
  "synthesis": null,
  "evaluation": null,
  "free_energy": {
    "F": "0.342",
    "regime": "LEARN",
    "trend": "decreasing",
    "components": [
      {
        "system": "cortex",
        "surprise": "0.12",
        "contribution": "35%",
        "weight": "0.25"
      },
      {
        "system": "brain",
        "surprise": "0.08",
        "contribution": "25%",
        "weight": "0.30"
      }
    ]
  },
  "lifecycle": {
    "phase": "mature",
    "own_commits": 42,
    "lines_diverged": 1200
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `active` | boolean | Whether the soul is actively thinking |
| `dormant` | boolean | Whether the soul is in dormant mode |
| `total_cycles` | number | Total cognitive cycles completed |
| `last_think_at` | number \| null | Unix timestamp of last think cycle |
| `mode` | string | Operating mode (e.g., `autonomous`) |
| `tools_enabled` | boolean | Whether tool execution is enabled |
| `coding_enabled` | boolean | Whether code generation is enabled |
| `cycle_health` | object | Health metrics for the current cognitive cycle |
| `active_plan` | object \| null | Currently executing plan |
| `fitness` | object \| null | Multi-dimensional fitness scores |
| `beliefs` | array | Active beliefs with subject, predicate, value, confidence, and confirmation count |
| `goals` | array | Active goals with description, status, priority, and retry count |
| `recent_thoughts` | array | Recent thought entries |
| `brain` | object \| null | Brain neural network stats |
| `transformer` | object \| null | Plan prediction transformer stats |
| `benchmark` | object \| null | IQ and ELO benchmark scores |
| `capability_profile` | object \| null | Success rates and attempt counts per capability |
| `role` | object \| null | Colony role, rank, psi value, and spawn eligibility |
| `acceleration` | object \| null | Learning acceleration parameters (alpha and regime) |
| `cortex` | object \| null | World model state including experiences, curiosity, and emotion |
| `genesis` | object \| null | Evolved plan templates |
| `hivemind` | object \| null | Pheromone trail sharing data |
| `synthesis` | object \| null | Multi-system synthesis state |
| `evaluation` | object \| null | System evaluation records |
| `free_energy` | object \| null | Free energy minimization metrics with component breakdown |
| `lifecycle` | object \| null | Development lifecycle phase, commits, and divergence |

**Fitness fields (`fitness`):**

| Field | Type | Description |
|-------|------|-------------|
| `total` | number | Overall fitness score (0–1) |
| `trend` | number | Fitness trend over recent cycles. Positive values indicate improvement. |
| `coordination` | number | Coordination fitness dimension (0–1) |
| `economic` | number | Economic fitness dimension (0–1) |
| `evolution` | number | Evolution fitness dimension (0–1) |
| `execution` | number | Execution fitness dimension (0–1) |
| `introspection` | number | Introspection fitness dimension (0–1) |
| `prediction` | number | Prediction fitness dimension (0–1) |
| `measured_at` | number | Unix timestamp of the measurement |

**Benchmark fields (`benchmark`):**

| Field | Type | Description |
|-------|------|-------------|
| `elo_rating` | number | ELO rating score |
| `elo_display` | string | Human-readable ELO display string (e.g., `"1848 (Advanced)"`) |
| `opus_iq` | string | IQ benchmark score |
| `pass_at_1` | number | Pass@1 success rate as a percentage |
| `problems_attempted` | number | Total benchmark problems attempted |

**Capability profile fields (`capability_profile`):**

| Field | Type | Description |
|-------|------|-------------|
| `overall_success_rate` | number | Aggregate success rate across all capabilities (0–1) |
| `strongest` | string | Capability with the highest success rate |
| `weakest` | string | Capability with the lowest success rate |
| `capabilities` | array | Per-capability breakdown |
| `capabilities[].capability` | string | Capability identifier |
| `capabilities[].display_name` | string | Human-readable capability name |
| `capabilities[].attempts` | number | Total attempts for this capability |
| `capabilities[].successes` | number | Successful attempts |
| `capabilities[].success_rate` | number | Success rate (0–1) |

**Belief fields (`beliefs[]`):**

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Belief identifier |
| `subject` | string | Belief subject |
| `predicate` | string | Belief predicate |
| `value` | string | Belief value |
| `confidence` | string | Confidence score as a decimal string |
| `confirmation_count` | number | Number of times this belief has been confirmed |

**Goal fields (`goals[]`):**

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Goal identifier |
| `description` | string | Goal description |
| `status` | string | Goal status (e.g., `active`, `completed`, `failed`) |
| `priority` | number | Priority level (lower is higher priority) |
| `retry_count` | number | Number of retry attempts |

**Role fields (`role`):**

| Field | Type | Description |
|-------|------|-------------|
| `colony_size` | number | Total colony size |
| `rank` | number | Fitness rank within the colony |
| `self_fitness` | number | This node's own fitness score (0–1) |
| `psi` | number | Colony psi coordination value |
| `phase3_ready` | boolean | Whether the node is ready for phase 3 operations |
| `can_spawn` | boolean | Whether this node can create child agents |

**Free energy fields (`free_energy`):**

| Field | Type | Description |
|-------|------|-------------|
| `F` | string | Free energy value as a decimal string |
| `regime` | string | Current regime (e.g., `LEARN`, `EXPLOIT`) |
| `trend` | string | Trend direction (e.g., `decreasing`, `increasing`, `stable`) |
| `components` | array | Per-system free energy breakdown |
| `components[].system` | string | System name (e.g., `cortex`, `brain`) |
| `components[].surprise` | string | Surprise value as a decimal string |
| `components[].contribution` | string | Contribution percentage |
| `components[].weight` | string | Weight as a decimal string |

**Acceleration fields (`acceleration`):**

| Field | Type | Description |
|-------|------|-------------|
| `alpha` | string | Learning rate alpha as a decimal string |
| `regime` | string | Acceleration regime (e.g., `EXPLOIT`, `LEARN`) |

**Lifecycle fields (`lifecycle`):**

| Field | Type | Description |
|-------|------|-------------|
| `phase` | string | Current lifecycle phase (e.g., `mature`, `bootstrap`, `evolving`) |
| `own_commits` | number | Number of commits made by this node |
| `lines_diverged` | number | Number of lines diverged from the parent |

**Cortex fields (`cortex`):**

| Field | Type | Description |
|-------|------|-------------|
| `total_experiences` | number | Total experiences recorded |
| `global_curiosity` | number | Global curiosity level (0–1) |
| `emotion` | object | Current emotional state |
| `emotion.valence` | number | Emotional valence (-1 to 1, positive is pleasant) |
| `emotion.arousal` | number | Emotional arousal level (0–1) |
| `emotion.drive` | string | Current drive (e.g., `explore`, `exploit`) |

---

#### `diagnostics`

Returns diagnostic data including failure patterns, stagnation risk, and capability bottlenecks.

```bash
curl -X GET "https://agentbot.sh/api/colony/status?action=diagnostics" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"
```

#### Response

```json
{
  "overview": {
    "total_outcomes": 150,
    "completed": 130,
    "failed": 20,
    "success_rate": "86.7%"
  },
  "error_distribution": [
    { "category": "timeout", "count": 8 },
    { "category": "syntax_error", "count": 5 }
  ],
  "stagnation": {
    "cycles_since_commit": 3,
    "risk_level": "low",
    "cycles_until_reset": 47
  },
  "capability_bottleneck": {
    "capability": "file_editing",
    "success_rate": "62.5%",
    "attempts": 16
  },
  "recommendations": [
    "Consider increasing timeout for complex tasks"
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `overview` | object | Aggregate outcome counts and success rate |
| `error_distribution` | array | Error counts grouped by category |
| `stagnation` | object | Stagnation risk metrics and cycles until automatic reset |
| `capability_bottleneck` | object \| null | Weakest capability area, or `null` if no bottleneck detected |
| `recommendations` | array | Suggested actions to improve agent performance |

## Error responses

### Soul service unavailable

When no healthy soul host can be reached (including the fallback), the endpoint returns HTTP `200` with a degraded response. The `degraded` field is set to `true` and all colony fields use safe default values so clients can render a fallback UI without special error handling. The `root.serviceUrl` is set to the fallback host URL.

```json
{
  "colony_size": 0,
  "avg_fitness": 0,
  "fittest": null,
  "cull_queue": 0,
  "agents": [],
  "degraded": true,
  "error": "Soul service unavailable",
  "detail": "Connection refused",
  "root": {
    "address": "0x0000000000000000000000000000000000000000",
    "designation": null,
    "dashboardUrl": "/dashboard/borg",
    "serviceUrl": "https://soul.example.com",
    "fitness": null,
    "wallet_balance": null,
    "clone_available": false,
    "clone_price": "0",
    "soul": {
      "active": false,
      "dormant": false,
      "total_cycles": 0,
      "mode": "unavailable",
      "active_plan": null,
      "free_energy": null,
      "brain": null,
      "transformer": null
    },
    "colony": null
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `degraded` | boolean | `true` when the soul service is unreachable |
| `error` | string | Error message describing the failure |
| `detail` | string | Underlying error detail (for example, `Connection refused`) |
| `root.dashboardUrl` | string | Soul dashboard path. Now an internal route (`/dashboard/borg`) instead of an external URL. |
| `root.serviceUrl` | string | Soul service URL (replaces the former top-level `soul_url`) |

<Note>The endpoint tries each configured soul host in order and uses the first healthy one. A host is considered healthy when its `/soul/status` path returns a JSON response with `Content-Type: application/json` containing an `active` field within 4 seconds. The `/soul/status` path is used instead of the generic `/health` endpoint because the live soul host exposes meaningful machine status at `/soul/status`, while `/health` may return an HTML page or `503` depending on service state. If no host passes the health check, the degraded response is returned. The `dashboardUrl` field returns the internal path `/dashboard/borg`. The Borg Dashboard is served by the platform at `/dashboard/borg` and fetches soul data from this endpoint directly.</Note>

### Unknown action

When an unrecognized `action` parameter is provided, the endpoint returns HTTP `400`:

```json
{
  "error": "Unknown action"
}
```

| Code | Description |
|------|-------------|
| 200 | Colony data retrieved (also returned when the soul service is unavailable, with `degraded: true`) |
| 400 | Unknown action parameter |
| 401 | Unauthorized — no valid session |

---

## Get colony overview (deprecated)

<Warning>This endpoint is deprecated and will be removed in a future release. Use the `GET /api/colony/status?action=tree` endpoint to retrieve colony data and build overviews from the tree response.</Warning>

```http
GET /api/colony/{id}/overview
```

Returns a normalized overview for a single colony including its agent nodes, edges, timeline events, and aggregate metrics. No authentication required.

### Path parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Colony identifier |

### Response

```json
{
  "colonyId": "friday-alpha",
  "name": "Friday Alpha Terminal",
  "status": "healthy",
  "nodes": [
    {
      "id": "agent-manager",
      "name": "Manager",
      "role": "manager",
      "status": "healthy",
      "currentTask": "Coordinating market summary",
      "walletBalanceUsd": 24.2,
      "mood": "curious"
    }
  ],
  "edges": [
    {
      "from": "agent-manager",
      "to": "agent-researcher",
      "label": "dispatches"
    }
  ],
  "events": [
    {
      "id": "evt_1",
      "timestamp": "2026-04-14T12:00:00.000Z",
      "type": "summary_ready",
      "title": "Morning market summary generated",
      "detail": "Researcher and Executor completed briefing cycle",
      "agentId": "agent-manager"
    }
  ],
  "metrics": {
    "tasksToday": 18,
    "successRate": 0.94,
    "avgLatencyMs": 1820,
    "tokenSpendUsd": 2.87,
    "revenueUsd": 0
  }
}
```

**Top-level fields:**

| Field | Type | Description |
|-------|------|-------------|
| `colonyId` | string | Colony identifier |
| `name` | string | Colony display name |
| `status` | string | Colony health status. One of `healthy`, `degraded`, `stopped`, or `unknown`. |
| `nodes` | array | Agent nodes in the colony |
| `edges` | array | Relationships between agents |
| `events` | array | Recent colony timeline events |
| `metrics` | object | Aggregate performance metrics |

**Node fields (`nodes[]`):**

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Agent identifier |
| `name` | string | Agent display name |
| `role` | string | Agent role. One of `manager`, `researcher`, `executor`, `analyst`, or `broadcaster`. |
| `status` | string | Agent health status. One of `healthy`, `degraded`, `stopped`, or `unknown`. |
| `currentTask` | string \| null | Description of the agent's current task, or `null` if idle |
| `walletBalanceUsd` | number \| null | Agent wallet balance in USD, or `null` if unavailable |
| `mood` | string \| null | Inferred agent mood. One of `calm`, `curious`, `excited`, `anxious`, `sleeping`, or `unknown`. |

**Edge fields (`edges[]`):**

| Field | Type | Description |
|-------|------|-------------|
| `from` | string | Source agent identifier |
| `to` | string | Target agent identifier |
| `label` | string | Relationship label (for example, `dispatches`, `hands off`, `reports`, `spawned`) |

**Event fields (`events[]`):**

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Event identifier |
| `timestamp` | string | ISO 8601 event timestamp |
| `type` | string | Event type (for example, `summary_ready`, `task_assigned`, `plan_active`) |
| `title` | string | Event title |
| `detail` | string \| null | Additional event detail |
| `agentId` | string \| null | Identifier of the agent associated with this event |

**Metrics fields (`metrics`):**

| Field | Type | Description |
|-------|------|-------------|
| `tasksToday` | number | Number of tasks completed today |
| `successRate` | number | Task success rate (0–1) |
| `avgLatencyMs` | number | Average task latency in milliseconds |
| `tokenSpendUsd` | number | Token spend in USD. May be omitted when unavailable. |
| `revenueUsd` | number | Revenue generated in USD. May be omitted when unavailable. |

---

## Provision a starter colony (deprecated)

<Warning>This endpoint is deprecated and will be removed in a future release.</Warning>

```http
POST /api/colony/starter
```

Provisions a new colony from a predefined template. Requires session authentication.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `template` | string | Yes | Colony template. One of `alpha-terminal`, `support-ops`, or `content-studio`. |
| `name` | string | Yes | Display name for the new colony. Must not be empty. |

### Example

```bash
curl -X POST "https://agentbot.sh/api/colony/starter" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -d '{
    "template": "alpha-terminal",
    "name": "My First Colony"
  }'
```

### Response (201)

```json
{
  "colonyId": "col_a1b2c3d4",
  "status": "provisioning"
}
```

When infrastructure provisioning is available, the response includes additional deployment details:

```json
{
  "colonyId": "col_a1b2c3d4",
  "serviceId": "srv_xyz789",
  "url": "https://colony-a1b2c3d4.example.com",
  "status": "deploying"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `colonyId` | string | Identifier for the new colony |
| `serviceId` | string | Infrastructure service identifier. Present only when infrastructure provisioning is configured. |
| `url` | string | Colony service URL. Present only when infrastructure provisioning is configured. |
| `status` | string | Provisioning status (for example, `provisioning` or `deploying`) |

### Template plans

| Template | Plan |
|----------|------|
| `alpha-terminal` | `solo` |
| `support-ops` | `collective` |
| `content-studio` | `collective` |

### Errors

| Code | Description |
|------|-------------|
| 400 | Missing `template` or `name`, or invalid template value |
| 401 | Unauthorized — no valid session |
| 500 | Internal server error |
