Kanthoruwa API ஆவணப்படுத்தல்
கடைசியாகப் புதுப்பிக்கப்பட்டது: 4 நவம்பர் 2026
கண்ணோட்டம்
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 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`.
மாதிரி கோரிக்கைகள்
முக்கியச் சொல்லின் மூலம் செயலில் உள்ள காலியிடங்களைத் தேடவும் (பக்கத்திற்கு 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 key தேவை, மேலும் அந்த நிறுவனத்தின் சொந்த வேலைகள் மற்றும் விண்ணப்பதாரர்களை மட்டுமே வழங்கும். அமைவு வழிகாட்டி மற்றும் ஆதரிக்கப்படும் அமைப்புகளின் பட்டியல்
உங்கள் டாஷ்போர்டில் நிறுவனம் பகுதியில் API key உருவாக்கி, அதை 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 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
உங்கள் டாஷ்போர்டில் 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))
}