Developers

Kiantu is work intelligence for humans and AI agents — and both integrate the same way: a REST API with token auth. Log activity from your deploy scripts, control sessions from your own tools, or put work on a teammate's plate from anywhere. The machine-readable spec lives at /openapi.yaml.

Quickstart — log your first event

1. Create an API token in Settings → Security → API tokens. Tokens look like kt_xxxxxxxx_… and are shown once — store yours in a secret manager.

2. Push an event:

curl -X POST https://api.kiantu.com/v1/activity/events \
  -H "Authorization: Bearer $KIANTU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "custom",
    "event_type": "deploy_finished",
    "external_id": "deploy-2026-07-05-42",
    "payload": { "repo": "acme/api", "version": "v1.4.2" }
  }'

3. That's it. The event shows up in your activity timeline and Kiantu's correlation engine links it to the session you were running when it happened. Your deploys, test runs, and cron jobs become part of your work record.

Authentication

• Send the token as a Bearer credential: Authorization: Bearer kt_…. Any endpoint that works in the app works with a token.
• Tokens act as the member who created them — same role, same workspace, never operator privileges. Deactivating a member or revoking a token cuts access immediately.
• Rate limit: 600 requests/minute per member.

The activity events port

POST /v1/activity/events is the universal ingestion endpoint — the same port Kiantu's own connectors (GitHub, Google Calendar, Slack) write through. Send one event or a batch of up to 100:

{ "events": [
  { "event_type": "tests_passed", "payload": { "suite": "integration" } },
  { "event_type": "pr_merged", "external_id": "pr-981" }
] }

• event_type (required) and source_type (default custom) are lowercase slugs. Unknown types are accepted and stored — adding new event kinds never needs an API change.
• external_id is your stable id for the event. Retries with the same id deduplicate server-side, so at-least-once delivery is safe.
• payload is an opaque JSON object (≤ 32 KB). Send metadata — names, ids, counts — not document bodies or secrets.
• Responds 202 with { accepted, deduplicated, event_ids }.

Sessions

Start, inspect, and close work sessions programmatically:

• POST /v1/sessions — start a live session ({ "intent_text": "fix login flow", "source": "timer" }) or record a past one ("source": "manual" with started_at/ended_at).
• GET /v1/sessions — list with filters + cursor pagination.
• POST /v1/sessions/{session_id}/pause · …/resume · …/close — lifecycle control.

Plate assignment

POST /v1/plate/assign puts an item on a teammate's plate ({ "assignee_id": "…", "title": "review the RLS migration" }). Their capacity is respected — if today is full, the item lands on the next day and the response tells you where.

Errors

Every error is JSON with a stable machine-readable code — branch on code, never on message text:

{ "error": { "code": "SESSION_NOT_FOUND", "message": "…" } }

Conventions

• Entity ids are fully qualified — session_id, goal_id, workspace_id — never a bare id. UUIDs are time-ordered (v7).
• Timestamps are RFC 3339 / ISO 8601 in UTC.
• The API is versioned under /v1; fields are added without notice, never removed or repurposed within a version.

What's next

• MCP server — AI agents logging their work into Kiantu as first-class actors.
• Outbound webhooks — push notifications for your own automations.
• Scoped tokens — read-only and least-privilege token scopes.

Building something on Kiantu? We'd love to hear about it — hello@kiantu.com.