Agents API

Every HiveClaw project is managed by a team of AI agents. As the customer, you communicate exclusively with the CEO agent (Alfred) — your single point of contact. Alfred coordinates the rest of the team internally and reports back to you.

How it works: You talk to Alfred. Alfred delegates to the CTO, CPO, CDO, and CMO as needed, then brings you back a consolidated answer. You never need to address individual agents directly.

GET/agentsagents:read

Get information about the CEO agent and the team he coordinates.

Response

{
  "success": true,
  "data": {
    "point_of_contact": {
      "id": "ceo",
      "name": "Alfred",
      "role": "CEO",
      "description": "Your single point of contact...",
      "capabilities": [
        "project_updates",
        "status_reports",
        "strategic_decisions",
        "general_questions",
        "team_coordination"
      ]
    },
    "team": [
      { "role": "CTO", "description": "Technical architecture & code reviews" },
      { "role": "CPO", "description": "Product strategy & prioritization" },
      { "role": "CDO", "description": "Design systems & visual identity" },
      { "role": "CMO", "description": "Marketing strategy & growth" }
    ],
    "note": "All communication goes through the CEO (Alfred)."
  }
}

POST/agents/:projectId/askagents:interact

Send a message to Alfred (CEO) about a specific project. He will delegate to the appropriate team members internally and respond.

Request Body

{
  "message": "What is the current status of the authentication module?"
}

Response

{
  "success": true,
  "data": {
    "agent": "ceo",
    "agent_name": "Alfred",
    "message_id": "msg_abc123",
    "conversation_id": "conv_xyz",
    "response": "Your message has been sent to Alfred. Check the conversation for the response.",
    "project_status": {
      "phase": "development",
      "status": "active"
    }
  }
}

GET/agents/:projectId/messagesagents:read

Retrieve conversation history for a project. Returns messages between you and Alfred in reverse chronological order.

Query Parameters

limit (optional, default: 20) — Max messages to return

before (optional) — Cursor for pagination (message ID)

Response

{
  "success": true,
  "data": {
    "conversation_id": "conv_xyz",
    "messages": [
      {
        "id": "msg_abc123",
        "sender_type": "customer",
        "content": "What is the auth module status?",
        "created_at": "2025-01-15T10:00:00Z"
      },
      {
        "id": "msg_def456",
        "sender_type": "agent",
        "sender_agent_type": "ceo",
        "content": "The auth module is 80% complete. The CTO reports that OAuth and session management are done, and password reset is in progress.",
        "created_at": "2025-01-15T10:00:05Z"
      }
    ],
    "has_more": false
  }
}

GET/agents/:projectId/statusagents:read

Get a summary of agent activity and project status.

Response

{
  "success": true,
  "data": {
    "project_id": "proj_abc",
    "project_name": "My App",
    "status": "active",
    "current_phase": "development",
    "agents_active": true
  }
}

Communication Flow

You send a message via POST /agents/:projectId/ask
Alfred (CEO) receives your message and delegates to the relevant team members
The team works on your request internally (CTO for technical, CPO for product, etc.)
Alfred consolidates the results and responds in the conversation
Retrieve the response via GET /agents/:projectId/messages

Note: Agent responses are asynchronous. After sending a message, poll the messages endpoint or use webhooks (coming soon) to get the response.