Kanthoruwa

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 vacancy
  • GET /api/categories — List job categories and subcategories
  • GET /api/companies — List companies with active vacancies
  • GET /api/locations/major-cities — List major-city search hubs
  • GET /api/locations/districts — List Sri Lankan districts
  • POST /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 requisitions
  • GET /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 link
  • PATCH /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))
}

Machine-readable resources