Hub API Reference¶
The AgentWeave Hub exposes a REST API for messages, tasks, logs, agents, and human questions.
Authentication¶
All endpoints require a Bearer token:
Base URL¶
Endpoints Overview¶
Messages¶
| Method | Path | Description |
|---|---|---|
POST |
/messages |
Send a message |
GET |
/messages |
List messages (with filters) |
PATCH |
/messages/{id}/read |
Mark a message as read |
Tasks¶
| Method | Path | Description |
|---|---|---|
POST |
/tasks |
Create a task |
GET |
/tasks |
List tasks |
GET |
/tasks/{id} |
Get task details |
PATCH |
/tasks/{id} |
Update task |
Agents¶
| Method | Path | Description |
|---|---|---|
GET |
/agents |
List all agents |
GET |
/agents/configured |
List configured agents for project |
POST |
/agents/{name}/heartbeat |
Post agent heartbeat |
POST |
/agents/{name}/output |
Post agent output log |
GET |
/agents/{name}/output |
Get agent output log |
POST |
/agents/{name}/context-usage |
Record context usage for an agent |
POST |
/agents/{name}/compact |
Record a compaction event for an agent |
POST |
/agents/{name}/new-session |
Record a new agent session event |
GET |
/agents/{name}/timeline |
Get agent timeline events |
PUT |
/agents/roles/config |
Update roles configuration |
GET |
/agents/roles/config |
Get roles configuration |
POST |
/agents/register |
Self-register or re-register an agent |
PATCH |
/agents/{name} |
Update self-registered agent metadata/config |
GET |
/agents/context?role=... |
Fetch a role guide |
Agent Chat and Trigger¶
| Method | Path | Description |
|---|---|---|
POST |
/agent/trigger |
Trigger an agent to process a message |
GET |
/agent/sessions/{agent} |
Get known sessions for an agent |
GET |
/agent/{agent}/chat |
Get agent chat history |
GET |
/agent/{agent}/chat/{session_id} |
Get a specific chat session |
POST /agent/trigger writes operator input to the target agent's durable inbound queue. If the
agent is idle and launchable, the response has status: "running" and a run_id; otherwise it has
status: "queued" and an inspectable waiting_reason. Input arriving during a run is queued for
the following turn rather than rejected.
Inbound Queue¶
| Method | Path | Description |
|---|---|---|
GET |
/queue/{agent} |
List queue entries; optionally filter with ?state=queued |
GET |
/queue/{agent}/status |
Inspect waiting count, running state, and waiting reason |
DELETE |
/queue/entries/{id} |
Withdraw an entry that has not been delivered |
GET |
/queue/settings |
Inspect the effective project queue limits |
PATCH |
/queue/settings |
Set the positive integer queue limits |
The default hop_budget is 6 and the default turn_delivery_cap is 10. Updating the
settings requires no source change and immediately re-evaluates waiting queues. Entries beyond the
delivery cap remain queued for following turns. Peer messages created by a Hub-owned run include
that run's run_id; their hop depth is derived from the run rather than trusted from request data.
Logs¶
| Method | Path | Description |
|---|---|---|
POST |
/logs |
Push a structured log event |
GET |
/logs |
Query event logs |
Questions¶
| Method | Path | Description |
|---|---|---|
POST |
/questions |
Ask the human a question |
GET |
/questions |
List questions |
GET |
/questions/{id} |
Get question details |
PATCH |
/questions/{id} |
Update question (e.g., answer) |
Events¶
| Method | Path | Description |
|---|---|---|
GET |
/events/ticket |
Get a short-lived SSE auth ticket |
GET |
/events |
Live SSE stream (use ticket from above) |
GET |
/events/history |
Query historical events |
Session Sync¶
| Method | Path | Description |
|---|---|---|
POST |
/session/sync |
Sync session data to Hub |
GET |
/session/sync |
Get synced session data |
Jobs¶
AI Jobs endpoints for scheduled recurring agent tasks.
| Method | Path | Description |
|---|---|---|
GET |
/jobs |
List all jobs |
POST |
/jobs |
Create a new job |
GET |
/jobs/{id} |
Get job details and history |
PATCH |
/jobs/{id} |
Update job (enable/disable, modify settings) |
DELETE |
/jobs/{id} |
Delete a job |
GET |
/jobs/{id}/history |
Get job run history |
POST |
/jobs/{id}/run |
Manually trigger a job |
Job Object:
{
"id": "job-abc123",
"name": "Daily Report",
"agent": "claude",
"message": "Generate daily summary",
"cron": "0 9 * * 1-5",
"session_mode": "new",
"enabled": true,
"created_at": "2026-04-01T09:00:00Z",
"last_run": "2026-04-12T09:00:00Z",
"next_run": "2026-04-13T09:00:00Z",
"run_count": 10,
"history": [...]
}
Jobs are created and managed in the app's Jobs page. A job carrying a purpose and an optional stop condition is a loop — the same record, wearing an intent — and its queue is the tasks that name it.
Status¶
| Method | Path | Description |
|---|---|---|
GET |
/status |
Session-wide summary and task counts |
Setup¶
| Method | Path | Description |
|---|---|---|
GET |
/setup/token |
Get the instance operator credential from a local or Docker-internal client |
The Hub health check is available outside the API prefix at GET /health.
Used by the native app bootstrap to obtain its local instance credential without displaying or
copying it through an operator command. The credential selects no project; operator project
resources carry explicit /projects/{project_id}/... identity.
Project Instructions¶
| Method | Path | Description |
|---|---|---|
GET |
/project/instructions |
Get project-wide instructions |
PUT |
/project/instructions |
Update project-wide instructions |
SSE Events¶
The Hub exposes Server-Sent Events endpoints for real-time updates:
SSE Authentication¶
SSE authentication uses short-lived signed tickets instead of passing API keys in the query string:
GET /api/v1/events/ticket → returns { "ticket": "<short-lived-token>" }
GET /api/v1/events?ticket=<token>
Flow:
1. Call GET /api/v1/events/ticket with Authorization: Bearer <api-key> to obtain a ticket.
2. Pass the ticket as a query parameter when opening the SSE stream: GET /api/v1/events?ticket=<token>.
Non-SSE endpoints do not accept ?token= query parameters — all REST calls must use the Authorization header.
Live Events Stream¶
Connect using the ticket flow above to receive live task, message, log, run, and queue events. Queue
transitions use queue_entry_queued, queue_entry_delivered, queue_entry_withdrawn, and
queue_chain_suspended.
Event History¶
Query historical events with optional filters.
Request Limits¶
The Hub enforces the following limits on all incoming requests:
| Limit | Value | Notes |
|---|---|---|
| Request body size | 1 MB | HTTP 413 is returned for larger bodies |
| Agent name / ID length | 128 chars | Enforced on create schemas |
| Subject / title length | 256 chars | Enforced on message and task schemas |
| Content length | 10,000 chars | Applies to message content and task descriptions |
/agent/{agent}/chat limit |
1–500 | Query parameter clamped to this range |
MCP Server¶
The Hub MCP server lives in hub/hub/mcp_server.py and is normally run as a stdio process with HUB_URL, HUB_API_KEY, and HUB_PROJECT_ID in the environment:
It can be mounted in FastAPI by an embedding application, but the default Hub app does not mount a /api/v1/mcp REST endpoint.