KalenderBase API

Integreer officiële Belgische kalenderdata in uw applicatie — fiscale deadlines, feestdagen, schoolvakanties, RSZ-data en meer.

REST JSON API

v1.0

Base URL: /api/v1

OpenAPI 3.0

llms.txt

Snel aan de slag: Maak een gratis account aan op /app, genereer een API key, en stuur je eerste request in 2 minuten.

Authenticatie

Alle API endpoints (behalve /categories en /api/v1) vereisen een API key.

Voeg je key toe als HTTP header of als query parameter:

# Als header (aanbevolen)
GET /api/v1/calendars
X-API-Key: kb_live_xxxxxxxxxxxxxxxx

# Als query parameter
GET /api/v1/calendars?api_key=kb_live_xxxxxxxxxxxxxxxx

API keys aanmaken: Inloggen → Account → API Keys

Rate limits

Limieten worden per dag (UTC middernacht) gereset.

Plan	Limiet	Opmerking
Free	100 req/dag	Max 5 events preview per kalender
Paid	2000 req/dag	Alle events, geen preview limiet

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Plan

Error responses

// 401 Unauthorized
{ "error": "API key vereist", "hint": "Voeg X-API-Key header toe..." }

// 404 Not Found
{ "error": "Kalender niet gevonden" }

// 429 Too Many Requests
{ "error": "Dagelijks limiet bereikt", "limit": 100, "reset": "Morgen om middernacht UTC" }

// 400 Bad Request
{ "error": "Zoekterm moet minimaal 2 tekens zijn (parameter: q)" }

Endpoints

GET /api/v1/calendars Lijst alle kalenders

Parameter	Type	Vereist	Beschrijving
category	string	optioneel	Filter op categorie: `fiscaal`, `sociale-zekerheid`, `vennootschappen`, `overheid`, `onderwijs`, `financieel`
tier	string	optioneel	`free` of `paid`
limit	integer	optioneel	Max aantal resultaten (standaard 20, max 100)
offset	integer	optioneel	Paginering offset (standaard 0)

// Voorbeeld response
{
  "total": 20,
  "limit": 20,
  "offset": 0,
  "calendars": [
    {
      "id": "feestdagen-belgie",
      "name": { "nl": "Feestdagen België", "fr": "Jours fériés Belgique" },
      "category": "overheid",
      "tier": "free",
      "icon": "🇧🇪",
      "subscriber_count": 1842,
      "ical_url": "/ical/public/feestdagen-belgie.ics"
    }
  ]
}

Probeer het

GET /api/v1/search Zoek kalenders en events

Parameter	Type	Vereist	Beschrijving
q	string	vereist	Zoekterm (min. 2 tekens) — doorzoekt kalender namen, beschrijvingen én event titels
type	string	optioneel	`all` (standaard), `calendars`, of `events`
category	string	optioneel	Beperkt zoekresultaten tot één categorie
from	date	optioneel	Events vanaf datum (YYYY-MM-DD)
to	date	optioneel	Events tot datum (YYYY-MM-DD)

GET /api/v1/search?q=btw&from=2026-01-01&to=2026-12-31

// Response
{
  "query": "btw",
  "total_results": 6,
  "calendars": [
    { "id": "btw-kwartaal", "name": { "nl": "BTW Kwartaalaangiftes" }, ... }
  ],
  "events": [
    {
      "id": "...",
      "calendar_id": "btw-kwartaal",
      "calendar_name": "BTW Kwartaalaangiftes",
      "title": { "nl": "BTW Q1 2026 — deadline indiening" },
      "start_date": "2026-04-20",
      "is_all_day": true
    }
  ]
}

GET /api/v1/events/upcoming Komende events (alle kalenders)

Handig voor dashboards, herinneringen en AI-assistenten die willen weten welke Belgische deadlines eraan komen.

Parameter	Type	Standaard	Beschrijving
days	integer	30	Hoeveel dagen vooruit (max 365)
category	string	—	Filter op categorie
limit	integer	20	Max 100

GET /api/v1/events/upcoming?days=60&category=fiscaal

// Response
{
  "from": "2026-04-13",
  "to": "2026-06-12",
  "days": 60,
  "total": 4,
  "events": [
    {
      "calendar_id": "btw-kwartaal",
      "calendar_name": "BTW Kwartaalaangiftes",
      "calendar_icon": "🧾",
      "title": { "nl": "BTW Q1 2026 — deadline indiening" },
      "start_date": "2026-04-20",
      "is_all_day": true
    }
  ]
}

GET /api/v1/calendars/:slug Detail van één kalender

GET /api/v1/calendars/btw-kwartaal

Beschikbare slugs: feestdagen-belgie, btw-kwartaal, btw-maand, personenbelasting, vennootschapsbelasting, rsz-kwartaal, ... (zie /api/v1/calendars voor volledige lijst)

GET /api/v1/calendars/:slug/events Alle events van een kalender

Parameter	Type	Beschrijving
year	integer	Filter op jaar (bijv. 2026)
from	date	Events vanaf datum
to	date	Events tot datum
limit	integer	Max 500 (paid) / 20 (free)
offset	integer	Paginering

GET /api/v1/calendars/btw-kwartaal/events?year=2026

GET /api/v1/categories Overzicht categorieën — geen auth vereist

GET /api/v1/categories

{
  "categories": [
    { "category": "fiscaal", "calendar_count": 8, "total_subscribers": 12400 },
    { "category": "overheid", "calendar_count": 4, "total_subscribers": 8900 }
  ]
}

API Key beheer

Keys aanmaken en beheren kan via de UI op /app → Account of via de API (JWT login vereist).

GET /api/v1/keys Jouw API keys (JWT auth)

Authorization: Bearer <jwt_token>
GET /api/v1/keys

POST /api/v1/keys Nieuwe API key genereren

POST /api/v1/keys
{ "name": "Mijn boekhoud-app" }

// Response
{
  "key": "kb_live_abc123...",     // Sla op! Slechts eenmalig zichtbaar
  "prefix": "kb_live_abc12345",
  "plan": "free"
}

DELETE /api/v1/keys/:prefix Key deactiveren

DELETE /api/v1/keys/kb_live_abc12345

Gebruik voor AI agents

Deze API is geoptimaliseerd voor gebruik door AI-assistenten en automatiseringsworkflows. De /llms.txt bevat een gestructureerde beschrijving van alle endpoints voor LLM-integratie.

Typische use cases voor AI agents:

// "Welke fiscale deadlines komen er aan in de volgende 30 dagen?"
GET /api/v1/events/upcoming?days=30&category=fiscaal

// "Zoek alle BTW-gerelateerde deadlines voor 2026"
GET /api/v1/search?q=btw&type=events&from=2026-01-01&to=2026-12-31

// "Geef me alle feestdagen voor dit jaar"
GET /api/v1/calendars/feestdagen-belgie/events?year=2026