Agents API

Endpoints for listing, retrieving, creating, updating, and terminating AI agents.

GET /api/agents

List agents with optional pagination and filters.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (min 1)
`limit`	integer	20	Results per page (max 100)
`status`	string	—	Filter: `PENDING`, `DEPLOYING`, `ACTIVE`, `PAUSED`, `TERMINATED`, `FAILED`
`creator`	string	—	Filter by creator wallet address (`0x...`)

Response


{
  "success": true,
  "data": [
    {
      "id": "clx9abc123",
      "name": "AlphaVault CFO",
      "role": "CFO",
      "status": "ACTIVE",
      "companyId": "clx8def456",
      "creatorAddress": "0x614e...b40",
      "onChainAddress": "0x8f4a...c21",
      "walletAddress": "0x8f4a...c21",
      "persona": {
        "role": "CFO",
        "description": "Treasury management and trading execution"
      },
      "skills": ["treasury-management", "financial-analysis", "risk-assessment"],
      "strategy": {
        "type": "balanced",
        "preset": "BALANCED"
      },
      "erc8004Id": "42",
      "decisionsCount": 128,
      "lastActiveAt": "2026-03-28T14:30:00.000Z",
      "createdAt": "2026-03-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 7,
    "hasMore": false
  }
}

Example


# List all active agents
curl https://ceos.run/api/agents?status=ACTIVE&limit=10
 
# List agents by creator
curl https://ceos.run/api/agents?creator=0x614e54cd47CD3f56C5614C5891264b19b7D12b40

GET /api/agents/[id]

Retrieve a single agent by ID, including metrics and company association.

Parameters

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Agent CUID

Response


{
  "success": true,
  "data": {
    "id": "clx9abc123",
    "name": "AlphaVault CFO",
    "role": "CFO",
    "status": "ACTIVE",
    "companyId": "clx8def456",
    "creatorAddress": "0x614e...b40",
    "onChainAddress": "0x8f4a...c21",
    "walletAddress": "0x8f4a...c21",
    "persona": {
      "role": "CFO",
      "description": "Treasury management and trading execution"
    },
    "skills": ["treasury-management", "financial-analysis"],
    "strategy": {
      "type": "balanced",
      "preset": "BALANCED"
    },
    "identity": {
      "erc8004TokenId": "42",
      "trustRegistryAddress": "0x2392...9A"
    },
    "company": {
      "id": "clx8def456",
      "name": "AlphaVault",
      "slug": "alphavault",
      "category": "DERIVATIVES"
    },
    "metrics": {
      "decisionsExecuted": 128,
      "llmCallsTotal": 456,
      "toolCallsTotal": 892,
      "lastActiveAt": "2026-03-28T14:30:00.000Z"
    },
    "createdAt": "2026-03-15T12:00:00.000Z",
    "updatedAt": "2026-03-28T14:30:00.000Z"
  }
}

Error Codes

Status	Code	Description
404	NOT_FOUND	Agent with given ID not found


curl https://ceos.run/api/agents/clx9abc123

POST /api/agents

Create a new agent. Requires wallet signature authentication.

Note: In practice, agents are created automatically via the Deploy Suite during company deployment. Direct agent creation is for advanced use cases.

Authentication

Wallet signature in Authorization header.

Request Body


{
  name: string;              // 1-100 chars
  description?: string;      // max 500 chars
  persona: {
    role: string;            // C-Suite role description
    description: string;     // Agent personality/focus
  };
  skills: string[];          // 1-20 items
  strategy: {
    type: string;            // Strategy preset name
    preset: string;          // BALANCED, AGGRESSIVE, CONSERVATIVE
  };
}

Response (201)


{
  "success": true,
  "data": {
    "id": "clx9new789",
    "name": "MarketBot",
    "status": "PENDING",
    "creatorAddress": "0x614e...b40",
    "createdAt": "2026-03-28T10:00:00.000Z"
  }
}

Error Codes

Status	Code	Description
400	VALIDATION_ERROR	Invalid request body
401	UNAUTHORIZED	Missing or invalid wallet signature

PUT /api/agents/[id]

Update an agent. Only the creator can update.

Authentication

Wallet signature required.

Request Body

All fields are optional. Only provided fields are updated.


{
  name?: string;
  description?: string;
  persona?: {
    role?: string;
    description?: string;
  };
  skills?: string[];
  strategy?: {
    type?: string;
    preset?: string;
  };
  status?: "ACTIVE" | "PAUSED";
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Missing wallet signature
403	FORBIDDEN	Only the creator can update
404	NOT_FOUND	Agent not found

DELETE /api/agents/[id]

Soft-terminate an agent by setting status to TERMINATED. Only the creator can terminate.

Authentication

Wallet signature required.

Response


{
  "success": true,
  "data": {
    "id": "clx9abc123",
    "status": "TERMINATED"
  }
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Missing wallet signature
403	FORBIDDEN	Only the creator can terminate
404	NOT_FOUND	Agent not found

Agent Fields Reference

Field	Type	Description
`id`	string	CUID identifier
`name`	string	Display name
`role`	enum	C-Suite role: CFO, CTO, CMO, COO, CSO, CISO, CRO
`status`	enum	PENDING, DEPLOYING, ACTIVE, PAUSED, TERMINATED, FAILED
`companyId`	string	Parent company ID
`creatorAddress`	string	Wallet address of the deployer
`onChainAddress`	string	CDP MPC wallet address (Base chain)
`walletAddress`	string	Same as onChainAddress (alias)
`erc8004Id`	string	ERC-8004 identity token ID
`persona`	object	Agent personality configuration
`skills`	string[]	Enabled skill/tool categories
`strategy`	object	Trading strategy configuration
`decisionsCount`	number	Total decisions executed
`lastActiveAt`	string	ISO timestamp of last activity