v2.0 Production
YAML Collection
Official Gazette Engine Act No. 29 of 1971

SpecialDays Sri Lanka API Documentation

The authoritative, enterprise-grade statutory gazette API for the Republic of Sri Lanka. Built for high-velocity e-commerce checkouts, banking settlement synchronization, automated DOMEX/Prompt courier buffers, and real-time astronomical Full Moon Poya lunar tracking.

0.8ms

Edge Anycast Speed

Persistent in-memory cache guarantees sub-millisecond responses globally.

Neon Serverless Ready

PostgreSQL with Drizzle ORM and automatic SSL schema provisioning.

300

300 RPM Live Quota

Standardized live developer keys with zero rate-limit surprises.

Live API Explorer & Latency Benchmarker

Execute live requests against our production edge routes right from this page.

Edge Response Payload
null

Quick Start

Test our public API with zero authentication. Query whether today is an official Sri Lankan statutory holiday in a single cURL command:

cURL Terminal Command
curl -s "https://slapi.vercel.app/api/v1/today"

Base URL & Environments

EnvironmentBase URLPerformance SLA
Production (Global Edge)https://slapi.vercel.app< 1.5ms Edge Anycast
Local Developmenthttp://localhost:3000Node.js / Next.js Runtime

Multi-Database Auto-Connector Engine

The platform features a zero-configuration Universal Database Auto-Connector with automatic health checks and failover. It auto-detects and connects to your cloud database in priority order, with graceful fallback to Embedded PostgreSQL (PGlite 16) ensuring 100% uptime:

Neon Serverless PostgreSQLWebSockets

NEON_DATABASE_URL or DATABASE_URL (*.neon.tech)

Supabase PostgreSQLSSL Pooler

SUPABASE_DATABASE_URL (*.supabase.co)

Vercel PostgresAnycast Edge

POSTGRES_URL / POSTGRES_PRISMA_URL

Embedded PGlite 16Auto-Failover

Real Postgres 16 running directly in Node.js

Automated Multi-Database Diagnostics

npm run db:test

Scans all registered environment variables, tests TLS handshakes, verifies the 10 relational tables, and ensures all 27 statutory holidays of 2026 are seeded.

Authentication & API Keys

All production API keys use the standardized prefix slk_live_. No test keys or ClickSnap legacy keys exist. Keys are hashed using SHA-256 at rest.

Pass your key via HTTP Bearer Header:
Authorization: Bearer slk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Or via URL query parameter:
https://slapi.vercel.app/api/v1/today?api_key=slk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API Endpoint Reference

Full parameter specifications, schemas, error formats, and multi-language snippets for each production route.

GET/api/v1/today
300 RPM (Live) / 60 RPM (Anon)

Evaluates whether today (or a specific date) is a statutory holiday, lunar Poya, or CBSL clearing pause.

Query Parameters

ParameterTypeRequiredDefaultDescription
datestringNoColombo Current DateTarget date in YYYY-MM-DD ISO format.
langstringNoallLocale translation: 'en', 'si', 'ta', or 'all'.

Integration Code Examples

curl -X GET "https://slapi.vercel.app/api/v1/today?date=2026-05-30&lang=all"
Example Response (200 OK)
{
  "success": true,
  "active": true,
  "data": {
    "id": "vesak-full-moon-poya-day",
    "slug": "vesak-full-moon-poya-day",
    "date": "2026-05-30",
    "country": "LK",
    "timezone": "Asia/Colombo",
    "title": {
      "en": "Vesak Full Moon Poya Day",
      "si": "වෙසක් පුර පසළොස්වක පෝය දිනය",
      "ta": "வைகாசி விசாக பௌர்ணமி தினம்"
    },
    "greeting": {
      "en": "Blessed Vesak to All!",
      "si": "සැමට ප්‍රීතිමත් වෙසක් මංගල්‍යයක් වේවා!",
      "ta": "அனைவருக்கும் இனிய விசாக தின நல்வாழ்த்துகள்!"
    },
    "category": "poya",
    "is_public_holiday": true,
    "is_bank_holiday": true,
    "is_mercantile_holiday": true,
    "cbsl_clearing_paused": true,
    "shipping_buffer_days": 1
  },
  "query_date": "2026-05-30",
  "timezone": "Asia/Colombo"
}
GET/api/v1/holidays
300 RPM

Fetches the full calendar of gazetted Sri Lanka holidays for 2026, filterable by legal scope.

Query Parameters

ParameterTypeRequiredDefaultDescription
filterstringNononeStatutory scope: 'public', 'bank', 'mercantile', or 'poya'.

Integration Code Examples

curl -X GET "https://slapi.vercel.app/api/v1/holidays?filter=bank"
Example Response (200 OK)
{
  "success": true,
  "total_statutory_holidays": 27,
  "jurisdiction": "Sri Lanka",
  "timezone": "Asia/Colombo (+05:30)",
  "holidays": [
    {
      "id": "duruthu-full-moon-poya-day",
      "slug": "duruthu-full-moon-poya-day",
      "date": "2026-01-02",
      "eventType": "poya",
      "isPublicHoliday": true,
      "isBankHoliday": true,
      "isMercantileHoliday": false
    }
  ]
}
GET/api/v1/days
300 RPM

Query days by year, month, holiday flags, and cultural category.

Query Parameters

ParameterTypeRequiredDefaultDescription
yearnumberNo2026Calendar year (e.g. 2026).
monthnumberNoallMonth index 1 to 12.
typestringNoallEvent category ('poya', 'national', 'religious').
bankbooleanNononeFilter by bank holiday.

Integration Code Examples

curl -X GET "https://slapi.vercel.app/api/v1/days?year=2026&month=5&bank=true"
Example Response (200 OK)
{
  "success": true,
  "count": 2,
  "data": [
    {
      "slug": "may-day",
      "date": "2026-05-01",
      "is_public_holiday": true,
      "is_bank_holiday": true,
      "is_mercantile_holiday": true
    }
  ]
}
GET/api/v1/health
Unlimited

Returns live system status, current Colombo time (+05:30), Neon database connectivity, and edge node health.

Integration Code Examples

curl -X GET "https://slapi.vercel.app/api/v1/health"
Example Response (200 OK)
{
  "status": "healthy",
  "service": "SpecialDays Sri Lanka Statutory & Cultural Engine",
  "version": "2.0.0",
  "jurisdiction": "LK",
  "timezone": "Asia/Colombo",
  "offset": "+05:30",
  "current_colombo_date": "2026-11-03",
  "current_colombo_time": "05:40:00",
  "database": {
    "status": "CONNECTED",
    "engine": "Neon Serverless PostgreSQL Ready"
  },
  "uptime_pct": 99.99
}
POST/api/v1/keys
10 per hour

Generates a new production API key (slk_live_...) with 300 requests/minute capacity.

Query Parameters

ParameterTypeRequiredDefaultDescription
emailstringYes-Developer account email address.
labelstringNoProduction KeyDescriptive label for the API key.

Integration Code Examples

curl -X POST "https://slapi.vercel.app/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@company.lk", "label": "Shopify Storefront"}'
Example Response (200 OK)
{
  "success": true,
  "message": "API Key created successfully.",
  "api_key": "slk_live_a8f902bc45de712398ab01cd56ef9876",
  "data": {
    "id": "e93f4128-4b72-4b8c-b019-3c819a584091",
    "key_masked": "slk_live_a8f9...9876",
    "label": "Shopify Storefront",
    "status": "active",
    "rate_limit_rpm": 300
  }
}
POST/api/v1/auth/otp/send
5 per 15 min

Dispatches a 6-digit one-time code to developer email via Resend transactional email.

Query Parameters

ParameterTypeRequiredDefaultDescription
emailstringYes-Developer email address.

Integration Code Examples

curl -X POST "https://slapi.vercel.app/api/v1/auth/otp/send" \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@company.lk"}'
Example Response (200 OK)
{
  "success": true,
  "message": "6-digit verification code sent to developer@company.lk via Resend",
  "expiresAt": "2026-11-03T06:05:00.000Z"
}

Error Codes & Diagnostics

All error responses follow an enterprise JSON envelope with deterministic machine-readable codes:

Error CodeStatusRoot CauseResolution
RATE_LIMIT_EXCEEDED429Exceeded 300 RPM quotaWait 60s or use cached responses
AUTH_REQUIRED401Developer session missingLogin via /auth/otp/send
INVALID_EMAIL400Malformed developer emailProvide valid RFC 5322 email
NOT_FOUND404Event slug or key UUID missingCheck slug against /holidays

Data Models & Gazette Schemas

GazetteHoliday Record (TypeScript)

interface GazetteHoliday {
  id: string;                     // e.g. "vesak-full-moon-poya-day"
  slug: string;                   // Canonical URI identifier
  date: string;                   // ISO "2026-05-30"
  countryCode: "LK";              // Sri Lanka
  timezone: "Asia/Colombo";       // UTC+05:30
  isPublicHoliday: boolean;       // Gazette Act No. 29 Section 2
  isBankHoliday: boolean;         // CBSL interbank clearing pause
  isMercantileHoliday: boolean;   // Commercial employment holiday
  cbsl_clearing_paused?: boolean; // Real-time clearance halt
  shipping_buffer_days?: number;  // 1-day checkout buffer
  translations: {
    en: { title: string; greeting: string; description: string; };
    si: { title: string; greeting: string; description: string; };
    ta: { title: string; greeting: string; description: string; };
  };
}

Versioning & Changelog

v2.0.0 (Current Production)November 2026
  • Added native Neon Serverless PostgreSQL support via @neondatabase/serverless and Drizzle ORM.
  • Integrated interactive documentation portal with live latency benchmarking and multi-language snippets.
  • Standardized domain strictly on https://slapi.vercel.app.
  • Enhanced dashboard live preview with Storefront.lk courier dispatch timeline.
  • Released comprehensive OpenAPI 3.1 specification and Postman collection.