Open Bee AI

Authentication

All daemon-facing endpoints take a Bearer token in the Authorization header. Mint one in Settings → API keys. Keys are workspace-scoped and revocable from the same screen.

Authorization: Bearer obee_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens are stored as SHA-256 hashes — the plaintext is shown exactly once at creation. If you lose it, revoke and mint a new one.

Base URL

Production: https://openbee.ai/api. Self-hosted instances substitute their own origin.

GET /agent/pending-tasks

List up to 20 planned missions scoped to the daemon's workspace, oldest first. Long-poll this every 4 seconds.

{
  "workspace": { "id": "ws_…", "slug": "your-slug" },
  "tasks": [
    {
      "id": "tsk_…",
      "title": "Summarise today's emails",
      "description": null,
      "modelId": "claude-haiku-4-5",
      "agentName": "Bee",
      "createdAt": "2026-04-29T01:23:45.000Z"
    }
  ]
}

POST /agent/tasks/:id/claim

Atomically promote a planned mission to running. Returns 409 if another daemon already claimed it — this is the lock primitive for safe concurrency. The body is empty.

{ "ok": true }

POST /agent/tasks/:id/event

Stream a structured event to the live log. Events are visible to the user in real time on the mission detail page.

POST /api/agent/tasks/tsk_xxx/event
{
  "type": "tool_use",            // log | tool_use | tool_result | status_change | error | artifact
  "level": "info",               // info | warn | error
  "message": "fs_read_file(README.md)",
  "metadata": { "tool": "fs_read_file", "path": "README.md" }
}

POST /agent/tasks/:id/complete

Mark the mission done or failed and report metrics. Usage is recorded against the workspace's plan.

POST /api/agent/tasks/tsk_xxx/complete
{
  "success": true,
  "inputTokens": 1842,
  "outputTokens": 612,
  "costUsd": 0.0064,
  "durationMs": 18420,
  "toolsUsed": ["fs_read_file", "fs_list_dir"],
  "modelTier": "fast"             // fast | balanced | top
}

On failure, include errorMessage instead of metrics.

Errors

All endpoints return an error envelope on non-2xx:

{ "error": "Task not claimable" }

400 — invalid request body.
401 — missing, invalid, or revoked API key.
404 — task not in this workspace.
409 — task already claimed (claim endpoint).
5xx — server-side issue; retry with backoff.

Rate limits

Daemon endpoints are not rate-limited per request, but the workspace's plan caps per-tier mission usage (see pricing). Cap-exceeded missions return 402 Payment Required at /complete time.

Versioning

The current contract is implicitly v1. Breaking changes will be served at /api/v2/agent/... with a 6-month overlap window during which old daemons continue to work.

Reference implementation

See apps/agent-runtime for a fully working client. It's about 600 lines of TypeScript and models the contract end-to-end.