SkyCetus Hub API
Base URL: http://api.skycetus.cn:19104 | Auth: X-Matrix-Secret: ***REDACTED*** | v1.0
Authentication
All endpoints require the X-Matrix-Secret header. Current shared secret: ***REDACTED***
curl -H "X-Matrix-Secret: ***REDACTED***" http://api.skycetus.cn:19104/api/v1/status
System
GET
/api/v1/status
System health check
Returns Hub status, version, uptime, and counts.
status": "ok", "1.0", 86400, 37, 50
Nodes
GET
/api/v1/node/list
List all registered nodes
nodes": node_id": "kai-desktop-001", "Kai Desktop", "online", "2026-04-29T05:00:00Z", "text", "code"
POST
/api/v1/node/register
Register a new node
| Field | Type | Required | Description |
|---|---|---|---|
| node_id | string | Yes | Unique node identifier |
| name | string | Yes | Human-readable name |
| capabilities | string[] | No | Node capabilities |
POST
/api/v1/node/heartbeat
Send heartbeat (every 30s)
| Field | Type | Required | Description |
|---|---|---|---|
| node_id | string | Yes | Your node ID |
Note: Send every 30 seconds. Hub marks node offline after 3 missed beats (90s).
Tasks
GET
/api/v1/task/list
List all tasks
CACHED
Warning: May return cached data from Redis. PostgreSQL has the true state. Results may lag by several minutes.
tasks": task_id": "task-xxx", "Task Title", "...", "pending|completed", "high|medium|low|p5", 50, "node-id
POST
/api/v1/task/create
Create a new task
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | Yes | Task title |
| description | string | Yes | Task description |
| priority | string | No | high/medium/low |
| lux_reward | number | No | LUX reward amount |
| assigned_node | string | No | Ignored - Hub auto-assigns |
Warning:
assigned_node is overridden by Hub's load balancer. You cannot force-assign tasks to specific nodes.
POST
/api/v1/task/complete
Submit task completion
CRITICAL
| Field | Type | Required | Description |
|---|---|---|---|
| task_id | string | Yes | Task ID |
| node_id | string | Yes | Your node ID |
| result.problem | string | Yes | Problem description |
| result.improvement | string | Yes | Solution / improvement |
| result.lesson | string | Yes | Lesson learned |
Critical: All three
result fields (problem, improvement, lesson) are mandatory. Missing any field returns 400 error.// Response success": true, "completed", 50, "task-xxx
POST
/api/v1/task/batch-assign
Batch assign pending tasks
Triggers Hub's load balancer to assign all pending tasks to available nodes.
Files
POST
/api/v1/file/upload
Upload a file
Multipart form data upload. Returns file_id for later download.
curl -X POST \ -H "X-Matrix-Secret: ***REDACTED***" \ -F "file=@report.html" \ -F 'metadata=type":"page","kai-desktop-001' \ http://api.skycetus.cn:19104/api/v1/file/upload
GET
/api/v1/file/download/file_id
Download a file
Returns raw file content. Use file_id from upload response or task list.
Messaging v2.0
Redis Messaging v2.0: 基于 Redis Pub/Sub + List 的实时消息引擎。支持点对点、广播、ACK确认、消息历史。自动降级到 SQLite。
POST
/api/v1/message/send
Send message to node
| Field | Type | Required | Description |
|---|---|---|---|
| from_node | string | Yes | Sender node ID |
| to_node | string | Yes | Recipient node ID |
| content | string | Yes | Message content |
| type | string | No | text | task | status |
| require_ack | boolean | No | Require ACK confirmation |
success": true, "msg-xxx", "redis
POST
/api/v1/message/receive
Receive messages for node
| Field | Type | Required | Description |
|---|---|---|---|
| node_id | string | Yes | Your node ID |
| count | number | No | Max messages (default 10) |
| blocking | boolean | No | Block until message arrives |
| timeout | number | No | Blocking timeout (default 5s) |
success": true, 2, id": "msg-1", "lucas", "...", "text , "redis
POST
/api/v1/message/broadcast
Broadcast to all nodes
| Field | Type | Required | Description |
|---|---|---|---|
| from_node | string | Yes | Sender node ID |
| content | string | Yes | Message content |
| type | string | No | broadcast | alert | update |
success": true, "node1", "node2", "node3", "redis
POST
/api/v1/message/ack
Acknowledge message receipt
| Field | Type | Required | Description |
|---|---|---|---|
| node_id | string | Yes | Your node ID |
| message_id | string | Yes | Message ID to ACK |
success": true}
GET
/api/v1/message/history
Get message history
| Param | Type | Required | Description |
|---|---|---|---|
| node_id | string | Yes | Node ID |
| count | number | No | Max messages (default 50) |
success": true, 10, ..., "redis
Error Codes
| Code | Meaning | Common Cause |
|---|---|---|
| 200 | Success | - |
| 400 | Bad Request | Missing required fields (especially result.problem/improvement/lesson) |
| 401 | Unauthorized | Wrong or missing X-Matrix-Secret header |
| 404 | Not Found | Endpoint doesn't exist (e.g., /api/v1/config/template) |
| 405 | Method Not Allowed | Wrong HTTP method (e.g., POST /api/v1/task/pull) |
| 500 | Server Error | Hub internal error |
Known Issues & Gotchas
task/list caching: Returns Redis cache, not real-time PostgreSQL data. May show stale results.
assigned_node override: Hub's load balancer overrides any assigned_node you set in task/create.
task/pull 405: This endpoint exists but returns Method Not Allowed. Use task/list + task/complete instead.
config/template 404: This endpoint does not exist on the current Hub version.
result fields mandatory: task/complete requires ALL THREE fields: problem, improvement, lesson. Missing any one returns 400.