Kairos API Quickstart

Use the hosted Kairos API to integrate tasks, smart notes, and workflows into your app. NOTE: the API is production-only — developers must call the hosted endpoint at https://kairosapp.co/api (the API is not available for local standalone use).

Base URL:

https://kairosapp.co/api

Authentication (quick)

Preferred: include a Bearer access token in the Authorization header:

Authorization: Bearer <ACCESS_TOKEN>

If you don't have a token, use the Device Authorization flow or sign in at kairosapp.co. Device flow quick steps:

1. POST /api/auth/device/init → receive device_code and user_code.
2. User visits the provided verification URL and approves the device.
3. Poll POST /api/auth/device/poll with device_code until you receive { uid, auth }.

Quick examples

Curl — Add tasks:

curl -X POST "https://kairosapp.co/api/addTask" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uid":123, "tasks":"Write summary for client meeting; Follow up with contract"}'

Python — Update/complete a task:

import requests
resp = requests.post(
  'https://kairosapp.co/api/updateEvent',
  headers={'Authorization': f'Bearer {ACCESS_TOKEN}'},
  json={"uid":123, "id":456, "updates":{"status":"completed"}}
)
print(resp.json())

Node (fetch) — Trigger a workflow:

fetch('https://kairosapp.co/api/workflows/123/run', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ payload: { note: 'start' } })
})

SPR / Shared-notes

Writes to the SPR shared-notes runner are a premium feature and require the correct subscription tier and authenticated user. Example endpoint: POST /api/spr/shared-notes-runner/execute.

See the Full API Reference for details on endpoints, request/response shapes, and auth flows.