කන්තෝරුව

Kanthoruwa API ලේඛනගත කිරීම

අවසන් යාවත්කාලීනය: 2026 නොවැම්බර් 4

දළ විශ්ලේෂණය

Kanthoruwa API යනු ශ්‍රී ලංකාවේ රැකියා වේදිකාව වන කන්තෝරුවේ පළ කර ඇති රැකියා ඇබෑර්තු සඳහා වන පොදු, කියවීමට පමණක් (read-only) JSON API සේවාවකි. එය වෙබ් අඩවිය, Kanthoruwa MCP සේවාදායකය සහ AI නියෝජිතයින් බලගන්වයි. සෑම ප්‍රතිචාරයක්ම JSON ආකෘතියෙන් ලැබේ.

  • මූලික URL (Base URL): https://api.kanthoruwa.com
  • ආකෘතිය: HTTPS හරහා JSON, UTF-8
  • පිරිවිතර (Specification): OpenAPI 3.1 ලේඛනය (සම්පූර්ණ පරාමිතීන් සහ ප්‍රතිචාර schemas)

සත්‍යාපනය (Authentication)

සත්‍යාපනයක් අවශ්‍ය නොවේ. ලේඛනගත කර ඇති සෑම endpoint එකක්ම පොදු සහ කියවීමට පමණක් වන බැවින්, API යතුරක් හෝ ගිණුමක් නොමැතිව එය ඇමතිය හැකිය. පැහැදිලි read-only අක්තපත්‍රයක් අවශ්‍ය නියෝජිතයින්ට නිර්නාමිකව ලියාපදිංචි වී public:read bearer token එකක් ලබා ගත හැකිය; විස්තර සඳහා auth.md බලන්න. API හරහා රැකියා ඇබෑර්තු පළ කිරීම හෝ සංස්කරණය කිරීම කළ නොහැක.

භාවිත සීමාවන්

API, MCP සේවාදායකය සහ A2A endpoint හරහා නිර්නාමික ප්‍රවේශය එක් IP ලිපිනයකට මිනිත්තුවකට ඉල්ලීම් 120 කට සීමා වේ. සෑම ප්‍රතිචාරයකම RateLimit සහ RateLimit-Policy headers අඩංගු වේ; සීමාව ඉක්මවූ විට 429 ප්‍රතිචාරය සමඟ Retry-After header එක ලැබේ.

ඔබ රැකියා දැන්වීමක් පෙන්වන විට, අපේක්ෂකයින්ට අයදුම් කිරීමට හැකි වන පරිදි එහි කන්තෝරුව රැකියා පිටුවට — සෑම ඇබෑර්තුවකම ඇති url ක්ෂේත්‍රයට — සබැඳියක් එක් කරන්න. ඉහළ සීමාවන්, තොග දත්ත හෝ වාණිජ භාවිතය සඳහා support@kanthoruwa.com අමතන්න.

අනුවාදකරණය සහ අත්හැරීම (Versioning & deprecation)

මෙය Kanthoruwa API හි 1 වන අනුවාදයයි. විශාල වෙනස්කම් නව ප්‍රධාන අනුවාදයක් ලෙස පමණක් නිකුත් වන අතර, එය Kanthoruwa-Version ඉල්ලීම් header එක මගින් තෝරා ගත හැකිය; 1 වන අනුවාදය ලබා ගැනීමට එය අත්හරින්න. අත්හරින ලද endpoints හෝ අනුවාද ඉවත් කිරීමට අවම වශයෙන් දින 90 කට පෙර Deprecation සහ Sunset ප්‍රතිචාර headers ආපසු ලබා දෙයි.

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`.

උදාහරණ ඉල්ලීම්

මූල පදය අනුව සක්‍රිය රැකියා ඇබෑර්තු සොයන්න (පිටුවකට ප්‍රතිඵල 20):

curl "https://api.kanthoruwa.com/api/vacancies?q=accountant&page=1"

slug මගින් එක් රැකියා ඇබෑර්තුවක් ලබා ගන්න:

curl "https://api.kanthoruwa.com/api/vacancies/{slug}"

රැකියා කාණ්ඩ සහ උප කාණ්ඩ ලැයිස්තුගත කරන්න:

curl "https://api.kanthoruwa.com/api/categories"

දෝෂ (Errors)

දෝෂ සඳහා සම්මත HTTP තත්ත්ව කේත සහ යන්ත්‍රයට කියවිය හැකි code, මිනිසාට කියවිය හැකි message සහ ඉල්ලීම නිවැරදි කරන ආකාරය පිළිබඳ hint අඩංගු JSON body එකක් භාවිතා වේ:

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"
}

error ක්ෂේත්‍රයේ සැමවිටම පණිවිඩය string එකක් ලෙස අඩංගු වේ. කේත අතර not_found, rate_limited සහ internal_error ඇතුළත් වේ.

සේව්‍යයන් සඳහා API සහ webhooks

සමාගම්වලට තම ATS, මානව සම්පත් පද්ධතිය හෝ CRM සමඟ අයදුම්කරුවන් සමමුහුර්ත කළ හැකිය. මෙම API ඉහත පොදු API එකෙන් වෙනස් වේ: එයට සමාගම් පාලන පුවරුවෙන් (සමාගම, ඉන්පසු ඒකාබද්ධ කිරීම්) API යතුරක් අවශ්‍ය වන අතර එම සමාගමේම රැකියා සහ අයදුම්කරුවන් පමණක් ලබා දෙයි. සැකසුම් මාර්ගෝපදේශය සහ සහාය දක්වන පද්ධති ලැයිස්තුව

ඔබේ පාලන පුවරුවේ සමාගම යටතේ API යතුරක් සාදා, එය Authorization header එකේ යවන්න. පිළිතුරු JSON ලෙස ලැබේ. CV සබැඳි අත්සන් කර ඇති අතර විනාඩි 15කින් පමණ කල් ඉකුත් වන බැවින්, ලැබුණු විගස ගොනුව බාගන්න.

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

ඔබේ පාලන පුවරුවේ webhook URL එකක් එක් කළ විට, යමක් වෙනස් වූ මොහොතේම අපි සිදුවීමක් POST කරමු. සිදුවීම් වර්ග: application.created, application.status_changed සහ ping (පරීක්ෂණ බොත්තම).

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"
    }
  }
}

අත්සන තහවුරු කරන්න

සෑම සිදුවීමකටම Kanthoruwa-Signature header එකක් ඇත: කාල මුද්‍රාවක් සහ කාල මුද්‍රාවේ හා මුල් body එකේ HMAC-SHA256 අගයක්, ඔබේ webhook අත්සන් රහසින් අත්සන් කර ඇත. අත්සන නොගැළපෙන හෝ කාල මුද්‍රාව විනාඩි පහකට වඩා පැරණි සිදුවීම් ප්‍රතික්ෂේප කරන්න.

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))
}

යන්ත්‍රයට කියවිය හැකි සම්පත්