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만 삭제할 수 있습니다. 실행 중인 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 시스템 이상 |