Workers API

REST endpoints for managing ZMQ workers and dispatching tasks. Workers connect via ZMQ ROUTER/DEALER and communicate using msgpack over ZMTP.

List ZMQ Workers

GET /api/v1/zmq/workers

Returns all currently connected ZMQ workers with their status and capabilities.

Response

{
  "items": [
    {
      "worker_id": "luna-worker-1",
      "status": "ready",
      "capabilities": ["lua", "streaming", "tools"],
      "connected_at": 1716192000000,
      "last_heartbeat": 1716192100000,
      "current_task": null
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Supports pagination via ?page=N&per_page=M query parameters.

CLI

zerg zmq-workers

ZMQ Gateway Status

GET /api/v1/zmq/status

Returns the ZMQ gateway configuration and current state.

Response

{
  "enabled": true,
  "port": 5555,
  "connected": 2,
  "queue_depth": 0
}

Field	Description
enabled	Whether the ZMQ gateway is running
port	ROUTER socket bind port
connected	Number of connected workers
queue_depth	Pending tasks in the dispatch queue

CLI

zerg zmq-status

Dispatch Task to Worker

POST /api/v1/zmq/dispatch

Dispatch a task to an available ZMQ worker. The gateway routes to the first ready worker.

Request

{
  "prompt": "Analyze the codebase and report issues",
  "model": "glm-5.1",
  "stream": true,
  "context": "additional context for the task"
}

Field	Required	Description
prompt	Yes	Task prompt to send to the worker
model	No	Model override for the task
stream	No	Enable SSE streaming (default: false)
context	No	Additional context string

Response (non-streaming)

{
  "status": "ok",
  "task_id": "task_abc123"
}

Response (streaming)

Returns SSE events with Content-Type: text/event-stream:

event: token
data: {"content": "Analyzing..."}

event: token
data: {"content": "Found 3 issues..."}

event: result
data: {"task_id": "task_abc123", "status": "ok", "content": "Complete analysis"}

Error Responses

Code	Description
400	Missing prompt
405	Method not POST
503	ZMQ gateway disabled
500	Dispatch failed

List JSONL Agents

GET /api/v1/agents

Returns JSONL stdio workers managed by Sol via erlexec.

Response

{
  "items": [
    {
      "id": "worker_1",
      "status": "running",
      "current_task": null
    }
  ]
}

Spawn JSONL Agent

POST /api/v1/agents/spawn

Spawn a new JSONL stdio worker process.

Request

{
  "worker_path": "/opt/zerg/luna/luna",
  "opts": {}
}

Kill JSONL Agent

DELETE /api/v1/agents/:id/kill

Terminate a running JSONL worker process.

Task Status

GET /api/v1/tasks/:task_id

Get the status and result of a dispatched task.

Response (completed)

{
  "task_id": "task_abc123",
  "status": "ok",
  "content": "Task result content"
}

Response (in progress)

{
  "task_id": "task_abc123",
  "status": "in_progress",
  "content": "partial output so far..."
}

Cancel a Task

DELETE /api/v1/tasks/:task_id

Cancel a running task. Returns 200 if cancelled, 404 if not found.

Response

{
  "status": "cancelled"
}

List Tasks

GET /api/v1/tasks

List all tasks, filtered by user ownership. Admin users see all tasks.

Response

{
  "items": [
    {
      "task_id": "task_abc123",
      "status": "ok",
      "created_at": 1716192000000
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Orchestrate

POST /api/v1/orchestrate

Dispatch multiple tasks in parallel or as a workflow.

Request

{
  "tasks": [
    {"prompt": "Analyze module A"},
    {"prompt": "Analyze module B"}
  ],
  "mode": "direct",
  "strategy": "parallel",
  "timeout": 120000
}

Field	Description
tasks	Array of task objects with prompt
mode	direct or workflow
strategy	parallel or sequential
timeout	Overall timeout in milliseconds
model	Model override for all tasks

Authentication

All worker endpoints require a Bearer token when authentication is enabled. Admin-only operations (dispatch, spawn, kill) require admin permissions.

curl -H "Authorization: Bearer $TOKEN" https://api.nonsense.ws/api/v1/zmq/workers

ZMQ Protocol

Workers connect as DEALER sockets to Sol's ROUTER on port 5555. The wire protocol uses msgpack. See Workers and Agents for the full protocol specification and worker implementation examples.