Kairos API Reference

The Kairos API is a production-hosted service. This documentation matches the live codebase in backend/ and explains the supported authentication methods, common endpoints, and recommended request patterns for third-party developers.

IMPORTANT: the API is only accessible at the hosted endpoint — you cannot run or access the same API locally for third-party integrations. Point all requests to the production Base URL and obtain tokens via the flows below.

Base URL (production):

https://kairosapp.co/api

Authentication

• Preferred: Bearer access tokens sent in the Authorization header.
  • Header: Authorization: Bearer <ACCESS_TOKEN>
  • The backend resolves users from bearer tokens and falls back to legacy uid+auth checks for some endpoints.
• Device Authorization and OAuth provider flows are supported to obtain user-scoped tokens (see "Authentication flows").
• Compatibility: Some legacy endpoints accept uid and auth in the JSON body. For widest compatibility include both the Authorization header and uid when applicable.

Error handling

All responses are JSON. On error the API returns an HTTP status code (400, 401, 403, 404, 500) and a body with an error key, for example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "error": "Invalid Token" }

Authentication flows

1) Device Authorization Flow (recommended for headless clients)

Start device flow:

POST https://kairosapp.co/api/auth/device/init
Content-Type: application/json
{ "client_name": "My CLI" }

You will receive a device_code / user_code pair and a verification_uri where the end user authorizes the device.

Poll the device token endpoint until approval:

POST https://kairosapp.co/api/auth/device/poll
Content-Type: application/json
{ "device_code": "..." }

On success the poll returns { "uid": <id>, "auth": "<ACCESS_TOKEN>", "token_type": "bearer" }.

2) OAuth provider login / provider exchanges

• Redirect users to /api/auth/<provider>/login (server performs provider redirect).
• To store provider tokens for a user the server supports both server-side exchange (POST /api/auth/<provider>/exchange with a Bearer <USER_TOKEN>) and a frontend-compatible exchange (POST /api/oauth/exchange with uid + auth).

3) Token refresh

Refresh flows are provider-specific and handled by the backend's OAuth managers. Contact support for service-account or extended refresh behavior.

Calling the API (recommended patterns)

• Always prefer Authorization: Bearer <ACCESS_TOKEN>.
• If an endpoint requires a uid in the body (many task/notes and legacy endpoints do), include uid in the request payload even when using Authorization.
• Respect production rate limits (applied per token/user). Contact support@kairosapp.co for quota increases.

Selected endpoints

The live backend supports both modern bearer tokens and legacy uid/auth checks; including both is the most compatible pattern.

For provider integrations (Google, Jira, Trello, Proton, Slack, GitHub) follow the OAuth/device flows above; provider tokens are persisted on the user account after exchange.

Request / response examples

Replace ACCESS_TOKEN, uid, and ids with real values from your integration.

1) Add tasks — POST /api/addTask

Request:

POST https://kairosapp.co/api/addTask
Headers: { "Authorization": "Bearer <ACCESS_TOKEN>", "Content-Type": "application/json" }
Body:
{
  "uid": 123,
  "tasks": "Prepare slides for meeting; Email Alice; Buy milk"
}

Response (201/200):

{
  "tasks": [
    { "id": 987, "task_name": "Prepare slides for meeting", "created_at": "2026-01-25T12:00:00Z", "status": "open" },
    { "id": 988, "task_name": "Email Alice", "created_at": "2026-01-25T12:00:01Z", "status": "open" }
  ]
}

Curl:

curl -X POST "https://kairosapp.co/api/addTask" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uid":123, "tasks":"Buy milk; Email Bob"}'

Python:

import requests
resp = requests.post(
    "https://kairosapp.co/api/addTask",
    json={"uid": 123, "tasks": "Buy milk"},
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
)
print(resp.json())

Node / fetch:

await fetch('https://kairosapp.co/api/addTask', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${ACCESS_TOKEN}` },
  body: JSON.stringify({ uid: 123, tasks: 'Buy milk' })
});

2) Update / complete a task — POST /api/updateEvent

Request:

{
  "uid": 123,
  "id": 987,
  "updates": { "status": "completed", "completed_at": "2026-01-25T15:30:00Z" }
}

Response:

{
  "success": true,
  "updated": { "id": 987, "status": "completed", "completed_at": "2026-01-25T15:30:00Z" }
}

3) Manual workflow trigger — POST /api/workflows/<workflow_id>/run

Request:

{
  "payload": { "report_name": "weekly_summary", "params": { "days": 7 } }
}

Response:

{ "success": true, "message": "Workflow run initiated" }

4) Device auth (init + poll)

Init response:

{
  "device_code": "abc123",
  "user_code": "ABCD-1234",
  "verification_uri": "https://kairosapp.co/device",
  "expires_in": 900,
  "interval": 5
}

Poll success response:

{
  "uid": 123,
  "auth": "<ACCESS_TOKEN>",
  "token_type": "bearer",
  "expires_in": 3600
}

5) Latest tasks — POST /api/latestTasks

Request:

{ "user_id": 123, "amount": 5 }

Response:

{
  "tasks": [
    { "task_name": "Buy milk", "time_utc": "2026-01-25T16:00:00Z", "user_tz": "America/New_York", "priority": 2 },
    { "task_name": "Call Alice", "time_utc": "2026-01-25T18:00:00Z", "user_tz": "America/New_York", "priority": 1 }
  ]
}

6) SPR shared-notes (premium) — POST /api/spr/shared-notes-runner/execute

Request:

{
  "operation": "write",
  "user_id": 123,
  "user_tier": "pro",
  "data": [ { "title": "Meeting notes", "content": "Discuss Q1 roadmap" } ]
}

Response (success):

{
  "status": "success",
  "usage_info": { "units_used": 12, "units_remaining": 988 }
}