Controller API¶

Django REST Framework API. Base URL: http://localhost:8000/api/v1/

Authentication: OAuth2 client credentials for external orchestrators, Token auth for operator tools.

Tasks¶

Callback¶

Receives task completion notifications from the Dispatcher.

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

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

See Callback Contract for the full schema and auth details.

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",
  "dispatcher_guid": "uuid",
  "dispatcher_slug": "slug"
}

The action field is created for new registrations, updated for existing dispatchers checking in again.

Heartbeat¶

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

Response:

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

Skills¶

List Skills¶

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

Response:

[
  {
    "guid": "uuid",
    "name": "code-review",
    "slug": "code-review",
    "category": "tool",
    "description": "Reviews code for quality."
  }
]

Create Skill¶

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

{
  "name": "My Skill",
  "category": "tool",
  "description": "What the skill does."
}

Upload Package¶

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

file: skill-package.zip

Response:

{
  "slug": "code-review",
  "storage_ref": "skills/code-review/e3b0c44..zip",
  "content_hash": "e3b0c44...",
  "version_number": 1,
  "deduplicated": false
}

Download Package¶

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

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

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"
}

Auto-detection

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

Health¶

Endpoint	Purpose
`GET /health/`	Liveness -- checks database connectivity
`GET /ready/`	Readiness -- checks database + Redis + MinIO