API Reference

REST API reference for Bee Worker and Bee Hive. All APIs return structured JSON.

Bee Worker API

Base URL: http://localhost:7433

Run an agent

Requesthttp

POST /agent/run
Content-Type: application/json

{
  "spec": "./agents/my-agent.yaml",
  "task": "Summarize the latest research on LLM agents",
  "context": {
    "session_id": "abc123",
    "metadata": {}
  }
}

Responsejson

{
  "run_id": "run_abc123",
  "status": "completed",
  "output": {
    "type": "structured",
    "content": { ... },
    "reasoning": "..."
  },
  "tool_calls": [...],
  "duration_ms": 2341,
  "tokens_used": 1820
}

List agents

GET /agent/list

→ { "agents": [{ "name": "...", "version": "..." }] }

Validate spec

POST /agent/validate
Content-Type: application/json

{ "spec_path": "./agents/my-agent.yaml" }

→ { "valid": true, "errors": [] }

Bee Hive API

Base URL: http://localhost:7434

Submit task

POST /task/submit
Content-Type: application/json

{
  "agent": "research-agent",
  "task": "...",
  "priority": "normal",
  "routing": { "prefer_region": "us-east" }
}

→ { "task_id": "task_xyz789", "status": "queued" }

Get task status

GET /task/{task_id}

→ { "task_id": "task_xyz789", "status": "completed", "result": { ... } }

Error format

All errors return structured JSON with a machine-readable code:

{
  "error": {
    "code": "TOOL_UNAVAILABLE",
    "message": "Tool 'web_search' is unavailable: connection refused",
    "agent": "research-agent",
    "tool": "web_search",
    "timestamp": "2025-05-24T10:30:00Z"
  }
}