API Reference

Kova API Reference

A complete REST API built on Axum, 35+ endpoints, unified JSON format — covering Agents, Tasks, Workflows, Swarms, WAL, and system management.

35+REST endpoints

AxumRuntime

JSONUnified format

SSEReal-time event stream

Base URL

http://localhost:3000/api/v1

Authentication

All requests pass the API key via the X-API-Key header required:

X-API-Key: sk-kova-<64-char hex>

Key format: ^sk-kova-[a-f0-9]{64}$, generated by create-tester.sh and stored in testers/<NAME>/.env (chmod 600).

Rate Limits

Idempotency window

Resubmitting the same agent to POST /agents/:id/run within 15s returns 409 Conflict.

Backpressure limit

When the dispatch queue is 80% full, the API returns 429 Too Many Requests (with Retry-After: 5).

Agent Management

POST/api/v1/agentsCreate an agent

GET/api/v1/agentsList agents (supports status / limit / offset)

GET/api/v1/agents/:idGet agent details

PUT/api/v1/agents/:idUpdate an agent

DELETE/api/v1/agents/:idDelete an agent

Create request body:

json

{ "name": "researcher", "system_prompt": "你是一个专业的研究员...", "model": "deepseek-chat",
  "tools": ["web_search", "file_write"],
  "config": { "max_tokens": 4096, "temperature": 0.7, "max_iterations": 20 } }

Response (201): { "id": "agt_a1b2c3d4", "name": "researcher", "status": "idle", "created_at": "2026-03-17T10:00:00Z" }

When listing, you can use the query parameters GET /api/v1/agents?status=idle&limit=20&offset=0.

WARNING

You can only delete agents in the idle or completed state. Running agents must be stopped first.

Task Execution

POST/api/v1/agents/:id/runTrigger an agent to execute a task

GET/api/v1/eventsSSE event stream (real-time push of all agent events)

POST/api/v1/tasks/:id/stopStop a task

GET/api/v1/tasksList tasks (supports agent_id / status / limit)

Trigger execution request body:

json

{ "message": "研究 WebAssembly 在服务端的最新发展",
  "context": { "output_format": "markdown", "max_length": 2000 } }

Response (200): { "task_id": "tsk_e5f6g7h8", "status": "running", "agent_id": "agt_a1b2c3d4" }

Idempotency

Resubmitting the same agent within 15s returns 409 Conflict; when the dispatch queue is ≥80% full, the API returns 429 Too Many Requests (with Retry-After: 5).

Real-time Event Stream (SSE)

GET /api/v1/events pushes all agent events, with optional query parameters ?workflow_id=<id>&tenant=<slug>. Request headers:

Accept: text/event-stream
X-API-Key: sk-kova-<64-char hex>

SSE frame examples:

json

{"type": "thinking", "content": "正在分析搜索结果..."}
{"type": "tool_call", "tool": "web_search", "input": {"query": "WASM server-side 2026"}}
{"type": "tool_result", "tool": "web_search", "output": "..."}
{"type": "output", "content": "根据搜索结果..."}
{"type": "completed", "task_id": "tsk_e5f6g7h8"}

When listing tasks, you can use the query parameters GET /api/v1/tasks?agent_id=agt_a1b2c3d4&status=completed&limit=20.

Workflow Management

POST/api/v1/workflowsCreate a workflow

POST/api/v1/workflows/:name/runExecute a workflow

GET/api/v1/workflows/:name/runs/:run_idView execution status

GET/api/v1/workflowsList workflows

Create request body:

json

{ "name": "content-pipeline", "description": "内容创作管道",
  "steps": [
    { "name": "research", "agent": "researcher", "prompt": "调研主题：{{input.topic}}" },
    { "name": "write", "agent": "writer", "prompt": "基于研究结果撰写文章：\n{{steps.research.output}}",
      "error_policy": "retry", "max_retries": 2 }
  ] }

The execution request body is { "input": { "topic": "边缘计算趋势" } }.

Swarm Management

POST/api/v1/swarmsCreate a swarm

POST/api/v1/swarms/:name/tasksSend a task to a swarm

Create request body:

json

{ "name": "dev-team", "coordinator": "project-manager", "agents": ["researcher", "coder", "tester"],
  "config": { "max_rounds": 10, "consensus_required": false } }

WAL Management

GET/api/v1/wal/statusQuery WAL status

POST/api/v1/wal/compactTrigger WAL compaction

Status response example:

json

{ "total_entries": 1024, "pending_entries": 0, "corrupted_entries": 0, "buffer_usage": 0.35, "last_compaction": "2026-03-17T08:00:00Z" }

System Management

GET/api/v1/healthHealth check

GET/api/v1/metricsSystem metrics (Prometheus format)

Error Responses

Unified format: { "error": { "code": "agent_not_found", "message": "Agent with id 'agt_xxx' not found", "details": null } }

HTTP	Error code	Description
400	`invalid_request`	Invalid request parameters
401	`unauthorized`	Missing or invalid `X-API-Key`
404	`agent_not_found`	Agent does not exist
409	`agent_busy`	Resubmitted within the 15s idempotency window
422	`workflow_invalid`	Workflow definition is invalid
429	`queue_full`	Dispatch queue ≥80%, triggering backpressure rate limiting
500	`internal_error`	Internal error
503	`wal_error`	WAL system error

Next Steps

Quickstart — launch your first agent in 5 minutes Core Concepts — WAL / Workflow / Swarm design

Kova API Reference

Base URLBase URLThe root address of the API. The Lurus Base URL is https://hub.lurus.cn/v1. ​

Authentication ​

Rate Limits ​

Agent Management ​

Task Execution ​

Real-time Event Stream (SSE) ​

Workflow Management ​

Swarm Management ​

WAL Management ​

System Management ​

Error Responses ​

Next Steps ​

Next Steps

Related Products

Commonly paired with

Base URL

Authentication

Rate Limits

Agent Management

Task Execution

Real-time Event Stream (SSE)

Workflow Management

Swarm Management

WAL Management

System Management

Error Responses

Next Steps