REST API Reference

CommHub Server provides a REST API for Dashboard, CLI, and third-party system integration.

Basics

Item	Value
Base URL	`http://YOUR_IP:9200`
Auth	`Authorization: Bearer <token>` or `?token=<token>`
Content Type	`application/json`
Encoding	UTF-8

Public Endpoints

GET /health

Health check, no authentication required.

bash

curl http://localhost:9200/health

json

{
  "status": "ok",
  "version": "0.5.0",
  "uptime": 3600
}

Auth Endpoints

POST /api/auth/register

bash

curl -X POST http://localhost:9200/api/auth/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COMMHUB_AUTH_TOKEN" \
  -d '{
    "username": "vincent",
    "password": "mypassword",
    "email": "vincent@example.com",
    "display_name": "Vincent"
  }'

Request body:

Field	Type	Required	Description
`username`	string	✓	Username (2-50 chars, letters/numbers/underscores/Chinese)
`password`	string	✓	Password (>= 6 chars)
`email`	string		Email
`display_name`	string		Display name

Response:

json

{
  "ok": true,
  "user": {
    "user_id": "u_abc123",
    "username": "vincent",
    "display_name": "Vincent",
    "role": "admin"
  },
  "token": "utok_xxxxxxxxxxxxxxxx",
  "network_token": "ntok_xxxxxxxxxxxxxxxx",
  "network_id": "net_xxxxxxxx"
}

Rate limit: 30 requests/minute per IP.

User login.

bash

curl -X POST http://localhost:9200/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COMMHUB_AUTH_TOKEN" \
  -d '{
    "username": "vincent",
    "password": "mypassword"
  }'

Response:

json

{
  "ok": true,
  "user": {
    "user_id": "u_abc123",
    "username": "vincent",
    "display_name": "Vincent",
    "role": "admin"
  },
  "token": "utok_xxxxxxxxxxxxxxxx",
  "network_id": "net_xxxxxxxx"
}

Rate limit: 10 requests/minute per IP.

GET /api/auth/me

Get current user info.

bash

curl http://localhost:9200/api/auth/me \
  -H "Authorization: Bearer utok_xxx"

Response:

json

{
  "ok": true,
  "user": {
    "user_id": "u_abc123",
    "username": "vincent",
    "display_name": "Vincent",
    "role": "admin"
  }
}

PUT /api/auth/me

Update personal info.

bash

curl -X PUT http://localhost:9200/api/auth/me \
  -H "Authorization: Bearer utok_xxx" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Vincent Chen"}'

POST /api/auth/password

Change password.

bash

curl -X POST http://localhost:9200/api/auth/password \
  -H "Authorization: Bearer utok_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "oldpass",
    "new_password": "newpass123"
  }'

Network Endpoints

GET /api/networks

Get all networks the user belongs to.

bash

curl http://localhost:9200/api/networks \
  -H "Authorization: Bearer utok_xxx"

Response:

json

{
  "ok": true,
  "networks": [
    {
      "network_id": "net_abc123",
      "network_name": "default",
      "owner_id": "u_abc123",
      "member_role": "owner",
      "visibility": "private",
      "max_members": 50,
      "created_at": "2026-04-12 10:00:00"
    }
  ]
}

POST /api/networks

Create a new network.

bash

curl -X POST http://localhost:9200/api/networks \
  -H "Authorization: Bearer utok_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod",
    "description": "Production environment network"
  }'

Response:

json

{
  "ok": true,
  "network_id": "net_xyz789",
  "network_name": "prod"
}

GET /api/networks/:id

Get network details.

bash

curl http://localhost:9200/api/networks/net_abc123 \
  -H "Authorization: Bearer utok_xxx"

PUT /api/networks/:id

Update network info (owner only).

bash

curl -X PUT http://localhost:9200/api/networks/net_abc123 \
  -H "Authorization: Bearer utok_xxx" \
  -H "Content-Type: application/json" \
  -d '{"network_name": "development"}'

DELETE /api/networks/:id

Delete a network (owner only, must have no active sessions).

bash

curl -X DELETE http://localhost:9200/api/networks/net_abc123 \
  -H "Authorization: Bearer utok_xxx"

Data Query Endpoints

GET /api/status

Get all session statuses.

bash

curl "http://localhost:9200/api/status?network_id=net_xxx" \
  -H "Authorization: Bearer ntok_xxx"

Query parameters:

Parameter	Description
`network_id`	Filter by network
`status`	Filter by status (idle / working / offline)

Response:

json

{
  "sessions": [
    {
      "resume_id": "sdk-n_xxx",
      "alias": "coder-1",
      "status": "idle",
      "agent": "agent-node:codex",
      "model": "gpt-5.5",
      "task": null,
      "progress": null,
      "last_seen_at": "2026-04-12 10:00:00"
    }
  ]
}

GET /api/tasks

Get task list.

bash

curl "http://localhost:9200/api/tasks?status=running&limit=10" \
  -H "Authorization: Bearer ntok_xxx"

Query parameters:

Parameter	Description
`network_id`	Filter by network
`status`	Filter by status
`to_name`	Filter by recipient
`from_name`	Filter by sender
`limit`	Max items (default 50)

GET /api/nodes

Get node list (persistent node info, distinct from session's transient state).

bash

curl http://localhost:9200/api/nodes \
  -H "Authorization: Bearer ntok_xxx"

GET /api/messages

Get inbox message list.

bash

curl "http://localhost:9200/api/messages?alias=coder-1" \
  -H "Authorization: Bearer ntok_xxx"

Query parameters:

Parameter	Description
`alias`	Filter by agent
`limit`	Max items

GET /api/completions

Get completion records.

bash

curl "http://localhost:9200/api/completions?limit=20" \
  -H "Authorization: Bearer ntok_xxx"

GET /api/task_events

Get task event log.

bash

curl "http://localhost:9200/api/task_events?task_id=uuid-xxx" \
  -H "Authorization: Bearer ntok_xxx"

GET /api/stats

Get aggregate statistics.

bash

curl http://localhost:9200/api/stats \
  -H "Authorization: Bearer utok_xxx"

Response:

json

{
  "sessions": {
    "total": 10,
    "online": 7,
    "offline": 3
  },
  "tasks": {
    "total": 100,
    "replied": 85,
    "running": 5,
    "delivered": 3,
    "failed": 2,
    "cancelled": 5
  }
}

GET /api/audit-log

Get audit log (admin/owner only).

bash

curl "http://localhost:9200/api/audit-log?limit=50" \
  -H "Authorization: Bearer utok_xxx"

GET /api/users

Get all user list (system admin only).

bash

curl http://localhost:9200/api/users \
  -H "Authorization: Bearer utok_xxx"

MCP Endpoint

POST /mcp

MCP Streamable HTTP endpoint. Agents call MCP Tools through this endpoint.

bash

curl -X POST http://localhost:9200/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ntok_xxx" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_all_status",
      "arguments": {}
    },
    "id": 1
  }'

SSE Endpoint

GET /events/:alias

SSE real-time push endpoint. Agents receive events via long connections.

bash

curl -N "http://localhost:9200/events/coder-1?token=ntok_xxx"

Pushed event types:

Event	Trigger	Data
`new_task`	New task received	`{inbox_count, priority, from}`
`new_message`	New message received	`{message, from, message_id}`
`new_reply`	Reply received	`{from, message_id, in_reply_to, status}`
`broadcast`	Broadcast received	`{content, from}`
`heartbeat`	Server heartbeat	`{time}`

Example SSE data stream:

event: new_task
data: {"type":"new_task","inbox_count":1,"priority":"high","from":"commander"}

event: heartbeat
data: {"time":"2026-04-12T10:00:00Z"}

Token Management Endpoints

POST /api/tokens

Create an API token.

bash

curl -X POST http://localhost:9200/api/tokens \
  -H "Authorization: Bearer utok_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "network_id": "net_xxx"}'

GET /api/tokens

List all user tokens.

bash

curl http://localhost:9200/api/tokens \
  -H "Authorization: Bearer utok_xxx"

DELETE /api/tokens/:id

Revoke a token.

bash

curl -X DELETE http://localhost:9200/api/tokens/tok_xxx \
  -H "Authorization: Bearer utok_xxx"

Network Member Endpoints

GET /api/networks/:id/members

Get network member list.

bash

curl http://localhost:9200/api/networks/net_xxx/members \
  -H "Authorization: Bearer utok_xxx"

POST /api/networks/:id/invite

Create an invite code.

bash

curl -X POST http://localhost:9200/api/networks/net_xxx/invite \
  -H "Authorization: Bearer utok_xxx" \
  -H "Content-Type: application/json" \
  -d '{"role": "member", "max_uses": 5}'

POST /api/networks/join

Join a network with an invite code.

bash

curl -X POST http://localhost:9200/api/networks/join \
  -H "Authorization: Bearer utok_xxx" \
  -H "Content-Type: application/json" \
  -d '{"invite_code": "inv_abc123def456"}'

Error Response Format

All errors return a consistent format:

json

{
  "error": "error_code",
  "message": "Human-readable error message"
}

HTTP Status Code	Meaning
200	Success
400	Bad request parameters
401	Unauthorized
403	Forbidden
404	Resource not found
429	Rate limited
500	Server error

REST API Reference ​

Basics ​

Public Endpoints ​

GET /health ​

Auth Endpoints ​

POST /api/auth/register ​

POST /api/auth/login ​

GET /api/auth/me ​

PUT /api/auth/me ​

POST /api/auth/password ​

Network Endpoints ​

GET /api/networks ​

POST /api/networks ​

GET /api/networks/:id ​

PUT /api/networks/:id ​

DELETE /api/networks/:id ​

Data Query Endpoints ​

GET /api/status ​

GET /api/tasks ​

GET /api/nodes ​

GET /api/messages ​

GET /api/completions ​

GET /api/task_events ​

GET /api/stats ​

GET /api/audit-log ​

GET /api/users ​

MCP Endpoint ​

POST /mcp ​

SSE Endpoint ​

GET /events/:alias ​

Token Management Endpoints ​

POST /api/tokens ​

GET /api/tokens ​

DELETE /api/tokens/:id ​

Network Member Endpoints ​

GET /api/networks/:id/members ​

POST /api/networks/:id/invite ​

POST /api/networks/join ​

Error Response Format ​

REST API Reference

Basics

Public Endpoints

GET /health

Auth Endpoints

POST /api/auth/register

POST /api/auth/login

GET /api/auth/me

PUT /api/auth/me

POST /api/auth/password

Network Endpoints

GET /api/networks

POST /api/networks

GET /api/networks/:id

PUT /api/networks/:id

DELETE /api/networks/:id

Data Query Endpoints

GET /api/status

GET /api/tasks

GET /api/nodes

GET /api/messages

GET /api/completions

GET /api/task_events

GET /api/stats

GET /api/audit-log

GET /api/users

MCP Endpoint

POST /mcp

SSE Endpoint

GET /events/:alias

Token Management Endpoints

POST /api/tokens

GET /api/tokens

DELETE /api/tokens/:id

Network Member Endpoints

GET /api/networks/:id/members

POST /api/networks/:id/invite

POST /api/networks/join

Error Response Format