Colony API

Query colony status, soul cognitive state, and diagnostics

Colony API

Retrieve colony status, agent fitness rankings, and soul service diagnostics.

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.

Get colony status

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.

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

Response

{
  "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
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 (active or stale)
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.

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.

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

Response

{
  "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,
    "economic": 0.78,
    "execution": 0.91,
    "evolution": 0.82,
    "coordination": 0.88,
    "introspection": 0.79,
    "prediction": 0.84,
    "measured_at": 1711152000
  },
  "beliefs": [],
  "goals": [],
  "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
  },
  "role": {
    "rank": 1,
    "can_spawn": true,
    "should_cull": false,
    "niche": "general",
    "colony_size": 3
  },
  "cortex": null,
  "genesis": null,
  "hivemind": null,
  "synthesis": null,
  "evaluation": null,
  "free_energy": null,
  "lifecycle": null
}

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 domain, confidence, and confirmation count
goals	array	Active goals with description, status, and priority
recent_thoughts	array	Recent thought entries
brain	object | null	Brain neural network stats
transformer	object | null	Plan prediction transformer stats
role	object | null	Colony role and rank
cortex	object | null	World model and prediction accuracy
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
lifecycle	object | null	Development lifecycle state

---

diagnostics

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

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

Response

{
  "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 the soul service cannot be reached, the endpoint returns HTTP 503:

{
  "error": "Soul service unavailable",
  "detail": "Connection refused",
  "soul_url": "https://openclaw-gw-ui-production.up.railway.app"
}

Unknown action

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

{
  "error": "Unknown action"
}

Code	Description
200	Colony data retrieved
400	Unknown action parameter
401	Unauthorized — no valid session
503	Soul service unavailable