yunxiafei/openclaw-mission-control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand API reference with route groups and key endpoints

Browse Source
This commit is contained in:
Abhimanyu Saharan
2026-02-11 06:33:03 +00:00
parent 73d2966332
commit 3d394afd3c
1 changed files with 255 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
docs/07-api-reference.md
View File

@@ -1,56 +1,269 @@
# API reference (first pass)
# API reference
## Deep dives
- [Gateway WebSocket protocol (API-ish)](openclaw_gateway_ws.md)
- [Architecture](05-architecture.md)
- [Gateway protocol](openclaw_gateway_ws.md)
This is a **map** of the Mission Control HTTP API surface. It’s intentionally light-weight for the first pass.
This page summarizes the **HTTP API surface** exposed by the FastAPI backend.
It is derived from `backend/app/main.py` (router registration) and `backend/app/api/*` (route modules).
## Base
- Backend service: `backend/app/main.py`
- API prefix: `/api/v1`
- API prefix: `/api/v1/*` (see `backend/app/main.py`)
## Auth
## Auth model (recap)
- **Clerk (user auth)**: used by the human web UI; frontend enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set; backend verifies JWTs when `CLERK_JWKS_URL` is configured (see `backend/app/core/auth.py`).
- **X-Agent-Token (agent auth)**: used by automation/agents; send header `X-Agent-Token: <token>` to `/api/v1/agent/*` endpoints (see `backend/app/core/agent_auth.py`).
### User/browser auth (Clerk)
- Used for the human UI.
- Frontend enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set.
- Backend verifies JWTs when `CLERK_JWKS_URL` is configured.
## Route groups (modules)
### Agent auth (X-Agent-Token)
- Used by automation/agents.
- Header: `X-Agent-Token: <token>`
- Agent endpoints live under `/api/v1/agent/*`.
| Module | Prefix (under `/api/v1`) | Purpose |
|---|---|---|
| `activity.py` | `/activity` | Activity listing and task-comment feed endpoints. |
| `agent.py` | `/agent` | Agent-scoped API routes for board operations and gateway coordination. |
| `agents.py` | `/agents` | Thin API wrappers for async agent lifecycle operations. |
| `approvals.py` | `/boards/{board_id}/approvals` | Approval listing, streaming, creation, and update endpoints. |
| `auth.py` | `/auth` | Authentication bootstrap endpoints for the Mission Control API. |
| `board_group_memory.py` | `` | Board-group memory CRUD and streaming endpoints. |
| `board_groups.py` | `/board-groups` | Board group CRUD, snapshot, and heartbeat endpoints. |
| `board_memory.py` | `/boards/{board_id}/memory` | Board memory CRUD and streaming endpoints. |
| `board_onboarding.py` | `/boards/{board_id}/onboarding` | Board onboarding endpoints for user/agent collaboration. |
| `boards.py` | `/boards` | Board CRUD and snapshot endpoints. |
| `gateway.py` | `/gateways` | Thin gateway session-inspection API wrappers. |
| `gateways.py` | `/gateways` | Thin API wrappers for gateway CRUD and template synchronization. |
| `metrics.py` | `/metrics` | Dashboard metric aggregation endpoints. |
| `organizations.py` | `/organizations` | Organization management endpoints and membership/invite flows. |
| `souls_directory.py` | `/souls-directory` | API routes for searching and fetching souls-directory markdown entries. |
| `tasks.py` | `/boards/{board_id}/tasks` | Task API routes for listing, streaming, and mutating board tasks. |
| `users.py` | `/users` | User self-service API endpoints for profile retrieval and updates. |
## Endpoint groups (routers)
Routers are registered in `backend/app/main.py`:
- `auth_router`
- `agent_router` (agent surface)
- `agents_router`
- `activity_router`
- `gateway_router`, `gateways_router`
- `metrics_router`
- `organizations_router`
- `souls_directory_router`
- `board_groups_router`, `board_group_memory_router`
- `boards_router`, `board_memory_router`, `board_onboarding_router`
- `approvals_router`
- `tasks_router`
- `users_router`
## `/activity` — `activity.py`
*Activity listing and task-comment feed endpoints.*
## Examples
### router (prefix `/activity`)
### Health
```bash
curl -s http://localhost:8000/healthz
```
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/activity` | `list_activity()` | List activity events visible to the calling actor. |
| `GET` | `/api/v1/activity/task-comments` | `list_task_comment_feed()` | List task-comment feed items for accessible boards. |
| `GET` | `/api/v1/activity/task-comments/stream` | `stream_task_comment_feed()` | Stream task-comment events for accessible boards. |
### Agent call (example)
```bash
curl -s http://localhost:8000/api/v1/agent/boards \
-H "X-Agent-Token: $AGENT_TOKEN"
```
## `/agent` — `agent.py`
*Agent-scoped API routes for board operations and gateway coordination.*
## Next
- Add a per-router table of key paths once we standardize which endpoints are “public” vs “internal”.
- If an OpenAPI schema exists/gets added, link it here.
### router (prefix `/agent`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/agent/agents` | `list_agents()` | List agents, optionally filtered to a board. |
| `POST` | `/api/v1/agent/agents` | `create_agent()` | Create an agent on the caller's board. |
| `GET` | `/api/v1/agent/boards` | `list_boards()` | List boards visible to the authenticated agent. |
| `POST` | `/api/v1/agent/heartbeat` | `agent_heartbeat()` | Record heartbeat status for the authenticated agent. |
| `GET` | `/api/v1/agent/boards/{board_id}` | `get_board()` | Return a board if the authenticated agent can access it. |
| `GET` | `/api/v1/agent/boards/{board_id}/tasks` | `list_tasks()` | List tasks on a board with optional status and assignment filters. |
| `POST` | `/api/v1/agent/boards/{board_id}/tasks` | `create_task()` | Create a task on the board as the lead agent. |
| `POST` | `/api/v1/agent/gateway/leads/broadcast` | `broadcast_gateway_lead_message()` | Broadcast a gateway-main message to multiple board leads. |
| `GET` | `/api/v1/agent/boards/{board_id}/memory` | `list_board_memory()` | List board memory entries with optional chat filtering. |
| `POST` | `/api/v1/agent/boards/{board_id}/memory` | `create_board_memory()` | Create a board memory entry. |
## `/agents` — `agents.py`
*Thin API wrappers for async agent lifecycle operations.*
### router (prefix `/agents`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/agents` | `list_agents()` | List agents visible to the active organization admin. |
| `POST` | `/api/v1/agents` | `create_agent()` | Create and provision an agent. |
| `GET` | `/api/v1/agents/stream` | `stream_agents()` | Stream agent updates as SSE events. |
| `POST` | `/api/v1/agents/heartbeat` | `heartbeat_or_create_agent()` | Heartbeat an existing agent or create/provision one if needed. |
| `DELETE` | `/api/v1/agents/{agent_id}` | `delete_agent()` | Delete an agent and clean related task state. |
| `GET` | `/api/v1/agents/{agent_id}` | `get_agent()` | Get a single agent by id. |
| `PATCH` | `/api/v1/agents/{agent_id}` | `update_agent()` | Update agent metadata and optionally reprovision. |
| `POST` | `/api/v1/agents/{agent_id}/heartbeat` | `heartbeat_agent()` | Record a heartbeat for a specific agent. |
## `/boards/{board_id}/approvals` — `approvals.py`
*Approval listing, streaming, creation, and update endpoints.*
### router (prefix `/boards/{board_id}/approvals`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/boards/{board_id}/approvals` | `list_approvals()` | List approvals for a board, optionally filtering by status. |
| `POST` | `/api/v1/boards/{board_id}/approvals` | `create_approval()` | Create an approval for a board. |
| `GET` | `/api/v1/boards/{board_id}/approvals/stream` | `stream_approvals()` | Stream approval updates for a board using server-sent events. |
| `PATCH` | `/api/v1/boards/{board_id}/approvals/{approval_id}` | `update_approval()` | Update an approval's status and resolution timestamp. |
## `/auth` — `auth.py`
*Authentication bootstrap endpoints for the Mission Control API.*
### router (prefix `/auth`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `POST` | `/api/v1/auth/bootstrap` | `bootstrap_user()` | Return the authenticated user profile from token claims. |
## `` — `board_group_memory.py`
*Board-group memory CRUD and streaming endpoints.*
### board_router (prefix `/boards/{board_id}/group-memory`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/boards/{board_id}/group-memory` | `list_board_group_memory_for_board()` | List memory entries for the board's linked group. |
| `POST` | `/api/v1/boards/{board_id}/group-memory` | `create_board_group_memory_for_board()` | Create a group memory entry from a board context and notify recipients. |
| `GET` | `/api/v1/boards/{board_id}/group-memory/stream` | `stream_board_group_memory_for_board()` | Stream memory entries for the board's linked group. |
### group_router (prefix `/board-groups/{group_id}/memory`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/board-groups/{group_id}/memory` | `list_board_group_memory()` | List board-group memory entries for a specific group. |
| `POST` | `/api/v1/board-groups/{group_id}/memory` | `create_board_group_memory()` | Create a board-group memory entry and notify chat recipients. |
| `GET` | `/api/v1/board-groups/{group_id}/memory/stream` | `stream_board_group_memory()` | Stream memory entries for a board group via server-sent events. |
## `/board-groups` — `board_groups.py`
*Board group CRUD, snapshot, and heartbeat endpoints.*
### router (prefix `/board-groups`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/board-groups` | `list_board_groups()` | List board groups in the active organization. |
| `POST` | `/api/v1/board-groups` | `create_board_group()` | Create a board group in the active organization. |
| `DELETE` | `/api/v1/board-groups/{group_id}` | `delete_board_group()` | Delete a board group. |
| `GET` | `/api/v1/board-groups/{group_id}` | `get_board_group()` | Get a board group by id. |
| `PATCH` | `/api/v1/board-groups/{group_id}` | `update_board_group()` | Update a board group. |
| `GET` | `/api/v1/board-groups/{group_id}/snapshot` | `get_board_group_snapshot()` | Get a snapshot across boards in a group. |
| `POST` | `/api/v1/board-groups/{group_id}/heartbeat` | `apply_board_group_heartbeat()` | Apply heartbeat settings to agents in a board group. |
## `/boards/{board_id}/memory` — `board_memory.py`
*Board memory CRUD and streaming endpoints.*
### router (prefix `/boards/{board_id}/memory`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/boards/{board_id}/memory` | `list_board_memory()` | List board memory entries, optionally filtering chat entries. |
| `POST` | `/api/v1/boards/{board_id}/memory` | `create_board_memory()` | Create a board memory entry and notify chat targets when needed. |
| `GET` | `/api/v1/boards/{board_id}/memory/stream` | `stream_board_memory()` | Stream board memory events over server-sent events. |
## `/boards/{board_id}/onboarding` — `board_onboarding.py`
*Board onboarding endpoints for user/agent collaboration.*
### router (prefix `/boards/{board_id}/onboarding`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/boards/{board_id}/onboarding` | `get_onboarding()` | Get the latest onboarding session for a board. |
| `POST` | `/api/v1/boards/{board_id}/onboarding/agent` | `agent_onboarding_update()` | Store onboarding updates submitted by the gateway agent. |
| `POST` | `/api/v1/boards/{board_id}/onboarding/start` | `start_onboarding()` | Start onboarding and send instructions to the gateway agent. |
| `POST` | `/api/v1/boards/{board_id}/onboarding/answer` | `answer_onboarding()` | Send a user onboarding answer to the gateway agent. |
| `POST` | `/api/v1/boards/{board_id}/onboarding/confirm` | `confirm_onboarding()` | Confirm onboarding results and provision the board lead agent. |
## `/boards` — `boards.py`
*Board CRUD and snapshot endpoints.*
### router (prefix `/boards`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/boards` | `list_boards()` | List boards visible to the current organization member. |
| `POST` | `/api/v1/boards` | `create_board()` | Create a board in the active organization. |
| `DELETE` | `/api/v1/boards/{board_id}` | `delete_board()` | Delete a board and all dependent records. |
| `GET` | `/api/v1/boards/{board_id}` | `get_board()` | Get a board by id. |
| `PATCH` | `/api/v1/boards/{board_id}` | `update_board()` | Update mutable board properties. |
| `GET` | `/api/v1/boards/{board_id}/snapshot` | `get_board_snapshot()` | Get a board snapshot view model. |
| `GET` | `/api/v1/boards/{board_id}/group-snapshot` | `get_board_group_snapshot()` | Get a grouped snapshot across related boards. |
## `/gateways` — `gateway.py`
*Thin gateway session-inspection API wrappers.*
### router (prefix `/gateways`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/gateways/status` | `gateways_status()` | Return gateway connectivity and session status. |
| `GET` | `/api/v1/gateways/commands` | `gateway_commands()` | Return supported gateway protocol methods and events. |
| `GET` | `/api/v1/gateways/sessions` | `list_gateway_sessions()` | List sessions for a gateway associated with a board. |
| `GET` | `/api/v1/gateways/sessions/{session_id}` | `get_gateway_session()` | Get a specific gateway session by key. |
| `GET` | `/api/v1/gateways/sessions/{session_id}/history` | `get_session_history()` | Fetch chat history for a gateway session. |
| `POST` | `/api/v1/gateways/sessions/{session_id}/message` | `send_gateway_session_message()` | Send a message into a specific gateway session. |
## `/gateways` — `gateways.py`
*Thin API wrappers for gateway CRUD and template synchronization.*
### router (prefix `/gateways`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/gateways` | `list_gateways()` | List gateways for the caller's organization. |
| `POST` | `/api/v1/gateways` | `create_gateway()` | Create a gateway and provision or refresh its main agent. |
| `DELETE` | `/api/v1/gateways/{gateway_id}` | `delete_gateway()` | Delete a gateway in the caller's organization. |
| `GET` | `/api/v1/gateways/{gateway_id}` | `get_gateway()` | Return one gateway by id for the caller's organization. |
| `PATCH` | `/api/v1/gateways/{gateway_id}` | `update_gateway()` | Patch a gateway and refresh the main-agent provisioning state. |
| `POST` | `/api/v1/gateways/{gateway_id}/templates/sync` | `sync_gateway_templates()` | Sync templates for a gateway and optionally rotate runtime settings. |
## `/metrics` — `metrics.py`
*Dashboard metric aggregation endpoints.*
### router (prefix `/metrics`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/metrics/dashboard` | `dashboard_metrics()` | Return dashboard KPIs and time-series data for accessible boards. |
## `/organizations` — `organizations.py`
*Organization management endpoints and membership/invite flows.*
### router (prefix `/organizations`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `POST` | `/api/v1/organizations` | `create_organization()` | Create an organization and assign the caller as owner. |
| `DELETE` | `/api/v1/organizations/me` | `delete_my_org()` | Delete the active organization and related entities. |
| `GET` | `/api/v1/organizations/me` | `get_my_org()` | Return the caller's active organization. |
| `GET` | `/api/v1/organizations/me/list` | `list_my_organizations()` | List organizations where the current user is a member. |
| `PATCH` | `/api/v1/organizations/me/active` | `set_active_org()` | Set the caller's active organization. |
| `GET` | `/api/v1/organizations/me/member` | `get_my_membership()` | Get the caller's membership record in the active organization. |
| `GET` | `/api/v1/organizations/me/invites` | `list_org_invites()` | List pending invites for the active organization. |
| `POST` | `/api/v1/organizations/me/invites` | `create_org_invite()` | Create an organization invite for an email address. |
| `GET` | `/api/v1/organizations/me/members` | `list_org_members()` | List members for the active organization. |
| `POST` | `/api/v1/organizations/invites/accept` | `accept_org_invite()` | Accept an invite and return resulting membership. |
## `/souls-directory` — `souls_directory.py`
*API routes for searching and fetching souls-directory markdown entries.*
### router (prefix `/souls-directory`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/souls-directory/search` | `search()` | Search souls-directory entries by handle/slug query text. |
| `GET` | `/api/v1/souls-directory/{handle}/{slug}` | `get_markdown()` | Fetch markdown content for a validated souls-directory handle and slug. |
| `GET` | `/api/v1/souls-directory/{handle}/{slug}.md` | `get_markdown()` | Fetch markdown content for a validated souls-directory handle and slug. |
## `/boards/{board_id}/tasks` — `tasks.py`
*Task API routes for listing, streaming, and mutating board tasks.*
### router (prefix `/boards/{board_id}/tasks`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `GET` | `/api/v1/boards/{board_id}/tasks` | `list_tasks()` | List board tasks with optional status and assignment filters. |
| `POST` | `/api/v1/boards/{board_id}/tasks` | `create_task()` | Create a task and initialize dependency rows. |
| `GET` | `/api/v1/boards/{board_id}/tasks/stream` | `stream_tasks()` | Stream task and task-comment events as SSE payloads. |
| `DELETE` | `/api/v1/boards/{board_id}/tasks/{task_id}` | `delete_task()` | Delete a task and related records. |
| `PATCH` | `/api/v1/boards/{board_id}/tasks/{task_id}` | `update_task()` | Update task status, assignment, comment, and dependency state. |
| `GET` | `/api/v1/boards/{board_id}/tasks/{task_id}/comments` | `list_task_comments()` | List comments for a task in chronological order. |
| `POST` | `/api/v1/boards/{board_id}/tasks/{task_id}/comments` | `create_task_comment()` | Create a task comment and notify relevant agents. |
## `/users` — `users.py`
*User self-service API endpoints for profile retrieval and updates.*
### router (prefix `/users`)
| Method | Path | Handler | Notes |
|---|---|---|---|
| `DELETE` | `/api/v1/users/me` | `delete_me()` | Delete the authenticated account and any personal-only organizations. |
| `GET` | `/api/v1/users/me` | `get_me()` | Return the authenticated user's current profile payload. |
| `PATCH` | `/api/v1/users/me` | `update_me()` | Apply partial profile updates for the authenticated user. |