Kova API リファレンス
Axum 上に構築された完全な REST API。35 以上のエンドポイント、統一された JSON フォーマット —— Agent、タスク、Workflow、Swarm、WAL、システム管理を網羅。
Base URLBase URLAPI のルートアドレス。Lurus の Base URL は https://hub.lurus.cn/v1 です。
http://localhost:3000/api/v1認証
すべてのリクエストは X-API-Key header で API key を渡します 必須：
X-API-Key: sk-kova-<64桁の16進数>key のフォーマット：^sk-kova-[a-f0-9]{64}$。create-tester.sh によって生成され、testers/<NAME>/.env（chmod 600）に保存されます。
レート制限
冪等性ウィンドウ
POST /agents/:id/run で 15s 以内に同一 agent を重複送信すると 409 Conflict を返します。バックプレッシャー制限
429 Too Many Requests（Retry-After: 5 を含む）を返します。Agent 管理
/api/v1/agentsAgent を作成/api/v1/agentsAgent を一覧表示（status / limit / offset をサポート）/api/v1/agents/:idAgent の詳細を取得/api/v1/agents/:idAgent を更新/api/v1/agents/:idAgent を削除作成リクエストボディ：
{ "name": "researcher", "system_prompt": "你是一个专业的研究员...", "model": "deepseek-chat",
"tools": ["web_search", "file_write"],
"config": { "max_tokens": 4096, "temperature": 0.7, "max_iterations": 20 } }レスポンス (201)：{ "id": "agt_a1b2c3d4", "name": "researcher", "status": "idle", "created_at": "2026-03-17T10:00:00Z" }
一覧表示時に使用できる query パラメータ GET /api/v1/agents?status=idle&limit=20&offset=0。
WARNING
削除できるのは idle または completed ステータスの Agent のみです。実行中のものは先に停止する必要があります。
タスク実行
/api/v1/agents/:id/runAgent にタスクの実行をトリガー/api/v1/eventsSSE イベントストリーム（すべての agent イベントをリアルタイムにプッシュ）/api/v1/tasks/:id/stopタスクを停止/api/v1/tasksタスクを一覧表示（agent_id / status / limit をサポート）実行トリガーのリクエストボディ：
{ "message": "研究 WebAssembly 在服务端的最新发展",
"context": { "output_format": "markdown", "max_length": 2000 } }レスポンス (200)：{ "task_id": "tsk_e5f6g7h8", "status": "running", "agent_id": "agt_a1b2c3d4" }
冪等性
15s 以内に同一 agent へ重複送信すると 409 Conflict を返します。dispatch キューが 80% 以上のときは 429 Too Many Requests（Retry-After: 5 を含む）を返します。
リアルタイムイベントストリーム（SSE）
GET /api/v1/events はすべての agent イベントをプッシュします。オプションの query パラメータ ?workflow_id=<id>&tenant=<slug> を使用できます。リクエストヘッダー：
Accept: text/event-stream
X-API-Key: sk-kova-<64桁の16進数>SSE フレームの例：
{"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"}タスク一覧で使用できる query パラメータ GET /api/v1/tasks?agent_id=agt_a1b2c3d4&status=completed&limit=20。
ワークフロー管理
/api/v1/workflowsワークフローを作成/api/v1/workflows/:name/runワークフローを実行/api/v1/workflows/:name/runs/:run_id実行ステータスを確認/api/v1/workflowsワークフローを一覧表示作成リクエストボディ：
{ "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 }
] }実行時のリクエストボディは { "input": { "topic": "边缘计算趋势" } } です。
Swarm 管理
/api/v1/swarmsSwarm を作成/api/v1/swarms/:name/tasksSwarm にタスクを送信作成リクエストボディ：
{ "name": "dev-team", "coordinator": "project-manager", "agents": ["researcher", "coder", "tester"],
"config": { "max_rounds": 10, "consensus_required": false } }WAL 管理
/api/v1/wal/statusWAL ステータスを照会/api/v1/wal/compactWAL のコンパクションをトリガーステータスレスポンスの例：
{ "total_entries": 1024, "pending_entries": 0, "corrupted_entries": 0, "buffer_usage": 0.35, "last_compaction": "2026-03-17T08:00:00Z" }システム管理
/api/v1/healthヘルスチェック/api/v1/metricsシステムメトリクス（Prometheus フォーマット）エラーレスポンス
統一フォーマット：{ "error": { "code": "agent_not_found", "message": "Agent with id 'agt_xxx' not found", "details": null } }
| HTTP | エラーコード | 説明 |
|---|---|---|
| 400 | invalid_request | リクエストパラメータが不正 |
| 401 | unauthorized | X-API-Key が欠落しているか無効 |
| 404 | agent_not_found | Agent が存在しない |
| 409 | agent_busy | 15s の冪等性ウィンドウ内での重複送信 |
| 422 | workflow_invalid | ワークフロー定義に誤りがある |
| 429 | queue_full | dispatch キューが 80% 以上、バックプレッシャーによるレート制限を発動 |
| 500 | internal_error | 内部エラー |
| 503 | wal_error | WAL システムの異常 |