API
Bee Flow exposes a REST + Server-Sent Events API. The frontend (hive) is one client; you can build others.
| Base URL | Use |
|---|---|
https://api.beeflow.ai | Hosted SaaS |
https://beeflow.example.com/api | Self-hosted |
http://localhost:3101/api | Local dev |
Pages
- Authentication — how to obtain a session JWT or API key.
- REST reference — endpoints by area.
- Streaming (SSE) — chat streams and tool-call events.
Versioning
Pre-1.0. The API is not versioned by URL prefix. Breaking changes will be:
- Announced in the release notes 30 days before they ship.
- Tagged with the new server version that drops the old behaviour.
- Held to a minimum during 0.x — most non-breaking additions follow.
If you need a version pin: pin the server image tag in your deploy. ghcr.io/bee-flow/beeflow:0.5.0 will speak the 0.5 protocol forever.
Deprecation policy
Endpoints marked Deprecated in this docs site:
- Continue to work for at least 6 months.
- Return a
Deprecation: <date>andSunset: <date>HTTP header. - Are removed in the first major version after the sunset date.
Error format
All errors return JSON:
{
"error": "tier_limit",
"message": "Your tier doesn't allow more than 20 agents",
"details": { "tier": "pro", "limit": 20, "current": 20 },
"requestId": "req_2026..."
}
| Status | When |
|---|---|
| 400 | Bad request — body or query is malformed. |
| 401 | Missing / invalid auth. |
| 402 | Tier limit hit (error: "tier_limit"). |
| 403 | Auth ok, but feature not in your tier (error: "license_feature_required"). |
| 404 | Not found / wrong tenant. |
| 409 | Conflict (e.g. duplicate idempotency key). |
| 422 | Semantic validation failed (e.g. invalid cron). |
| 429 | Rate-limited. Retry-After header present. |
| 500 | Server bug. requestId lets us trace it. |
| 503 | Upstream model provider down or overloaded. |
Rate limits
Default per-IP + per-user limits at the reverse proxy (self-hosters) and at the SaaS edge:
| Endpoint family | Default | Burst |
|---|---|---|
/api/chat | 60 / min | 120 |
/api/agents | 120 / min | 200 |
/api/knowledge/* | 30 / min | 60 |
/auth/* | 30 / min | 60 |
/api/automation/webhook/* | 600 / min | 1200 |
Set on the reverse proxy or via RATE_LIMIT_* env vars on the server (Redis-backed).
Idempotency
Every POST that creates a resource accepts an optional Idempotency-Key header. The server caches the first response for 24h and replays it on duplicate keys. Use a UUID per logical operation.
POST /api/agents
Idempotency-Key: 9d8a-...
CORS
The hosted SaaS allows requests from https://beeflow.ai. Self-hosted: configure via CORS_ALLOWED_ORIGINS= (comma-separated). For embedded chat, list every parent origin.