Skip to content

API Reference

The Kairos API is documented using OpenAPI 3 with interactive Scalar UI.

Accessing the API Docs

Start the API server first:

make backend        # Postgres + migrations + API
# or the full stack with the web UI:
make dev
# ./start.sh also works (it delegates to `make backend`)

Then open: http://localhost:8880/docs

Base URL

All endpoints are under /api/v1:

http://localhost:8880/api/v1/

Endpoints Overview

Method Path Description
GET /health Health check
POST /jobs/search Search jobs across platforms
GET /jobs List saved jobs (cursor pagination)
POST /jobs Add a job from its link (platform manual)
GET /jobs/{id} Get job details
POST /jobs/{id}/fetch-details Re-scrape full description
DELETE /jobs/{id} Delete a job
POST /jobs/{id}/apply Mark a job as applied (records a timeline event)
PATCH /jobs/{id}/status Change a job's status (records a timeline event)
GET /jobs/{id}/events The job's application timeline, oldest first
POST /jobs/{id}/events Record a status change (manual or agent)
GET /jobs/{id}/events/{event_id} One timeline event
POST /jobs/{id}/events/{event_id}/revert Undo the job's latest change
GET /applications Jobs in an application status, latest change first
POST /mail-suggestions/sync Read new mail from Kioku and add status suggestions
GET /mail-suggestions Suggestions waiting for review (pending and orphan)
POST /mail-suggestions/{id}/accept Record a suggestion as an email event
POST /mail-suggestions/{id}/ignore Dismiss a suggestion
GET /config View current configuration
PATCH /config Update configuration

OpenAPI Spec

Raw spec available at: http://localhost:8880/openapi.json