API reference
All endpoints require an authenticated session (cookie) or a Bearer API key. Responses are JSON. Errors return { error: string }.
Base URL
https://your-kairos-instance.comAll paths below are relative to your deployment URL.
Tasks
| GET | /api/tasks | List tasks (supports ?status=, ?tagId= filters) |
| POST | /api/tasks | Create a task. Schedule-on-write: auto-places into GCal. |
| GET | /api/tasks/:id | Get a single task with tags |
| PATCH | /api/tasks/:id | Update a task |
| DELETE | /api/tasks/:id | Delete a task and its GCal event |
Tags
| GET | /api/tags | List all tags |
| POST | /api/tags | Create a tag |
| PATCH | /api/tags/:id | Update a tag |
| DELETE | /api/tags/:id | Delete a tag |
Schedule
| GET | /api/schedule/windows | List schedule windows |
| PUT | /api/schedule/windows | Replace all schedule windows |
| POST | /api/schedule/run | Enqueue a full schedule run (chunked jobs) |
Scratchpad
| GET | /api/scratchpad | List scratchpad entries |
| POST | /api/scratchpad | Create a scratchpad entry |
| POST | /api/scratchpad/:id/process | Dispatch to plugin, returns candidate tasks |
| POST | /api/scratchpad/:id/commit | Create tasks from candidates + auto-schedule |
| DELETE | /api/scratchpad/:id | Delete a scratchpad entry |
Plugins
| GET | /api/plugins | List installed plugins with enabled state |
| GET | /api/plugins/:name | Get plugin details + config |
| PATCH | /api/plugins/:name | Update plugin config or enable/disable |
Themes
| GET | /api/themes/installed | List user's installed marketplace themes |
| POST | /api/themes/install | Install a theme from registry URL or raw manifest |
| DELETE | /api/themes/:installId | Uninstall a marketplace theme |
| GET | /api/themes/:installId/css | Serve compiled theme CSS (cached) |
| PATCH | /api/me/theme | Set active theme pack ID |
Calendars
| GET | /api/calendars | List connected Google Calendars |
| PATCH | /api/calendars/:id | Update calendar selected/showAsBusy flags |
| POST | /api/calendars/sync | Sync calendar list from Google |
Authentication
Session cookies are set automatically after Google OAuth sign-in. For headless clients (agents, n8n, CLI), add an Authorization: Bearer <key>header. API keys are managed via Better Auth's built-in key management (coming soon to the Settings UI).
Rate limits
No rate limits in self-hosted mode. Hosted mode (kairos.app) enforces per-user limits.