Kanthoruwa API documentation
Last updated: 4 November 2026
Overview
The Kanthoruwa API is a public, read-only JSON API for the job vacancies listed on Kanthoruwa, Sri Lanka's job board. It powers the website, the Kanthoruwa MCP server and AI agents. Every response is JSON.
- Base URL:
https://api.kanthoruwa.com - Format: JSON over HTTPS, UTF-8
- Specification: OpenAPI 3.1 document (full parameters and response schemas)
Authentication
No authentication is required. Every documented endpoint is public and read-only, so you can call it without an API key or account. Agents that want an explicit read-only credential can register anonymously and get a public:read bearer token, as described in auth.md. Posting or editing vacancies is not available through the API.
Usage limits
Anonymous API access is limited to 120 requests per minute per IP address, while AI agent endpoints (/mcp, /a2a, and Bearer agent requests) are limited to 20 requests per minute and 60 requests per hour per IP. Every response carries RateLimit and RateLimit-Policy headers; over the limit you get 429 with a Retry-After header.
When you show a listing, link to its Kanthoruwa job page — the url field on every vacancy — so candidates can apply. For higher limits, bulk data or commercial use, contact support@kanthoruwa.com.
Versioning and deprecation
This is version 1 of the Kanthoruwa API. Breaking changes ship only as a new major version, selected with the Kanthoruwa-Version request header; leave it out to get version 1. Deprecated endpoints or versions return Deprecation and Sunset response headers at least 90 days before they are removed.
Endpoints
GET /api/vacancies— List active job vacancies. Public job board. Returns 20 results per page, newest and featured first.GET /api/vacancies/{slug}— Get one vacancyGET /api/categories— List job categories and subcategoriesGET /api/companies— List companies with active vacanciesGET /api/locations/major-cities— List major-city search hubsGET /api/locations/districts— List Sri Lankan districtsPOST /mcp— MCP Streamable HTTP endpoint. Stateless Model Context Protocol endpoint. Tools: `search`, `fetch`, `list_categories`. Send JSON-RPC 2.0 requests with `Content-Type: application/json` and `Accept: application/json, text/event-stream`.
Example requests
Search active vacancies by keyword (20 results per page):
curl "https://api.kanthoruwa.com/api/vacancies?q=accountant&page=1"
Get one vacancy by its slug:
curl "https://api.kanthoruwa.com/api/vacancies/{slug}"List job categories and subcategories:
curl "https://api.kanthoruwa.com/api/categories"
Errors
Errors use standard HTTP status codes and a JSON body with a machine-readable code, a human-readable message and a hint on how to fix the request:
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error": "No route for GET /api/nope",
"code": "not_found",
"message": "No route for GET /api/nope",
"hint": "Check the path and method against the OpenAPI document at https://kanthoruwa.com/.well-known/openapi.json.",
"status": 404,
"docs": "https://kanthoruwa.com/docs"
}The error field always holds the message as a string. Codes include not_found, rate_limited and internal_error.
Employer API and webhooks
Companies can sync applicants with their ATS, HR system or CRM. This API is separate from the public one above: it needs an API key from the company dashboard (Company, then Integrations) and only returns that company's own jobs and applicants. Setup guide and list of supported systems
Create an API key in your dashboard under Company, then send it in the Authorization header. Responses are JSON. CV links are signed and expire after about 15 minutes, so download the file when you receive it.
curl https://api.kanthoruwa.com/api/v1/applications?since=2026-11-01T00:00:00Z \ -H "Authorization: Bearer kth_your_key"
Endpoints
GET /api/v1/vacancies— Your jobs, to map to requisitionsGET /api/v1/applications?since=<ISO date>&vacancyId=&limit=— Applicants, oldest change first (max 100)GET /api/v1/applications/{id}— One applicant with a signed CV linkPATCH /api/v1/applications/{id}— Move a candidate: {"status":"shortlisted"}
Webhooks
Add a webhook URL in your dashboard and we POST an event the moment something changes. Event types: application.created, application.status_changed and ping (the test button).
POST https://your-endpoint.example.com/kanthoruwa
Kanthoruwa-Signature: t=1795200000,v1=5f1c…
{
"id": "3b6f…",
"type": "application.created",
"createdAt": "2026-11-21T09:30:00.000Z",
"data": {
"application": {
"id": "8d2e…",
"status": "submitted",
"candidate": { "name": "Nimal Perera", "email": "nimal@example.com" },
"vacancy": { "id": "a41c…", "title": "Accountant", "ref": "ACC-12" },
"coverLetter": "…",
"cvUrl": "https://…signed link, valid ~15 min",
"createdAt": "2026-11-21T09:30:00.000Z",
"updatedAt": "2026-11-21T09:30:00.000Z"
}
}
}Verify the signature
Every event carries a Kanthoruwa-Signature header: a timestamp and an HMAC-SHA256 of the timestamp and raw body, signed with your webhook's signing secret. Reject events whose signature doesn't match or whose timestamp is more than five minutes old.
import { createHmac, timingSafeEqual } from "node:crypto"
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")))
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex")
return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}