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://tempo-x402-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

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Colony API

Colony API

Get colony status

Query parameters

Actions

`tree`

Response

`soul`

Response

`diagnostics`

Response

Error responses

Soul service unavailable

Unknown action

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Documentation Index

​Colony API

​Get colony status

​Query parameters

​Actions

​tree

​Response

​soul

​Response

​diagnostics

​Response

​Error responses

​Soul service unavailable

​Unknown action

Colony API

Get colony status

Query parameters

Actions

`tree`

Response

`soul`

Response

`diagnostics`

Response

Error responses

Soul service unavailable

Unknown action