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:
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