API Reference¶

Controller API (Django REST Framework)¶

Base URL: http://localhost:8000/api/v1/

Tasks¶

Callback¶

POST /api/v1/tasks/{guid}/callback/
Authorization: Bearer {callback_token}
X-Kohakku-Signature: sha256={hmac}  (if CALLBACK_SIGNING_KEY set)

{
  "status": "completed|failed|timed_out",
  "exit_code": 0,
  "result_key": "results/guid/output.json",
  "result_metadata": {},
  "error_message": ""
}

Dispatchers¶

Check-in¶

POST /api/v1/dispatchers/checkin/

{
  "name": "local-dev",
  "endpoint_url": "http://dispatcher:8080",
  "cloud": "local",
  "backends": ["local"],
  "labels": {},
  "heartbeat_interval_seconds": 60
}

Response: {"status": "ok", "action": "created|updated", "dispatcher_guid": "uuid", "dispatcher_slug": "slug"}

Heartbeat¶

POST /api/v1/dispatchers/{guid}/heartbeat/

Response: {"status": "ok", "dispatcher_guid": "uuid"}

Skills¶

Upload Package¶

POST /api/v1/skills/{slug}/upload/
Content-Type: multipart/form-data
Authorization: Token {token}

file: skill-package.zip

Response: {"slug": "...", "storage_ref": "...", "content_hash": "...", "version_number": 1, "deduplicated": false}

Download Package¶

GET /api/v1/skills/{slug}/download/
Authorization: Token {token}

Response: application/zip
X-Content-Hash: {sha256}

List Skills¶

GET /api/v1/skills/
Authorization: Token {token}

Response: [{"guid": "...", "name": "...", "slug": "...", ...}]

Create Skill¶

POST /api/v1/skills/
Authorization: Token {token}
Content-Type: application/json

{"name": "My Skill", "category": "tool", "description": "..."}

Webhooks¶

Ingest¶

POST /api/v1/webhooks/
X-Webhook-Source: github|slack|custom
X-Webhook-Event: push|pull_request|event_callback

{...event payload...}

Response: {"status": "ok", "routed_to": "workflow-id"}

GitHub webhooks auto-detected via X-GitHub-Event header. Slack webhooks auto-detected via X-Slack-Signature header.

Dispatcher API (Go + Chi)¶

Base URL: http://localhost:8080/

Tasks¶

Create Task¶

POST /tasks
X-API-Key: {api_key}
Content-Type: application/json

{
  "task_id": "uuid",
  "agent_image": "kohakku-agent-terminal:latest",
  "runtime_target": {"type": "local", "namespace": ""},
  "resources": {"cpu": "1", "memory": "2Gi"},
  "env": {"KEY": "value"},
  "ports": [{"container_port": 6080, "protocol": "tcp"}],
  "brief_key": "briefs/guid/hash.json",
  "callback_url": "http://controller:8000/api/v1/tasks/guid/callback/",
  "callback_token": "token",
  "timeout_seconds": 3600
}

Response: {"ok": true, "data": {...task...}}

Get Task¶

GET /tasks/{id}
X-API-Key: {api_key}

Response: {"ok": true, "data": {...task...}}

List Tasks¶

GET /tasks?limit=50&offset=0
X-API-Key: {api_key}

Response: {"ok": true, "data": {"tasks": [...], "total": N}}

Cancel Task¶

POST /tasks/{id}/cancel
X-API-Key: {api_key}

Response: {"ok": true}

Agent Protocol¶

Check-in¶

POST /agent/checkin
X-Agent-Key: {agent_key}
Content-Type: application/json

{"task_id": "uuid"}

Response: {"ok": true, "data": {"brief_key": "...", "env": {...}}}

Check-back¶

POST /agent/checkback
X-Agent-Key: {agent_key}
Content-Type: application/json

{
  "task_id": "uuid",
  "status": "completed|failed",
  "result_key": "results/output.json",
  "result_metadata": {},
  "error": ""
}

Response: {"ok": true}

Progress Report¶

POST /agent/progress
X-Agent-Key: {agent_key}
Content-Type: application/json

{
  "task_id": "uuid",
  "percentage": 0-100,
  "message": "Processing step 3/5...",
  "data": {}
}

Response: {"ok": true}

Health¶

GET /health
Response: {"ok": true}

GET /ready
Response: {"ok": true, "checks": {"database": "ok", "redis": "ok"}}