API

API documentation

The Paņem brīvdienu API returns Latvian public holidays, day counts, leave plans and annual leave estimates as JSON. It covers 2026 and 2027 and assumes a Monday-to-Friday workweek. The browser interface uses the same API.

The machine-readable description is the OpenAPI document, and /.well-known/api-catalog lists the API for automated discovery (RFC 9727).

Access and limits

The API is open without a key. Anonymous clients get 10 requests per second with a burst of 20. An API key raises that to 100 per second with a burst of 200; send it as Authorization: Bearer YOUR_API_KEY. An unknown key returns 401 and a used-up limit returns 429. Request a key through the contact form.

MCP

AI clients can use the same calculations as an MCP server at https://panembrivdienu.lv/mcp (streamable HTTP, no account needed). Its tools are latvia_holidays, latvia_calendar_statistics, latvia_plan_time_off and latvia_leave_entitlement; the same limits and API keys apply. For example, in Claude Code: claude mcp add --transport http panembrivdienu https://panembrivdienu.lv/mcp. llms.txt has the setup for other clients.

Holidays

GET /api/v1/calendar/{year}/holidays lists the statutory holidays of 2026 or 2027 by date, each with date, name_lv, name_en and is_moved_day.

Add apply_transfers=true to apply the 2026 workday transfers, which exchange January 2 with January 17 and June 22 with June 27. They apply to specified state-funded institutions and other employers that adopt them, and are only available for 2026.

Year statistics

GET /api/v1/calendar/{year}/statistics counts the year's working days, weekend days, holidays and total days off. It takes the same apply_transfers parameter.

Leave planner

POST /api/v1/optimize with {"year": 2027, "pto_days": 10} lists up to ten breaks, best first. Each takes every working day between two or more runs of weekends and holidays and joins them, using at most pto_days leave days on its own. Optional fields are apply_transfers, constraints.employment_start_date and extra_days_off (up to 100 dates that count as days off). Leave days are never before today in Latvian time.

Annual leave estimate

POST /api/v1/entitlement with employment_start_date, year, fte_percentage (0.1 to 1), annual_base (28 to 60 calendar days) and optionally birth_date estimates annual leave in calendar days, excluding statutory holidays. For a first-year employee the figure is an accrual estimate.

Health

GET /api/v1/health returns {"status": "ok"} while the service is up.

Errors

Errors return {"error": {"code": "...", "message": "...", "request_id": "..."}} with codes such as VALIDATION_ERROR, INVALID_JSON, REQUEST_TOO_LARGE (bodies over 64 KiB), INVALID_API_KEY and RATE_LIMIT_EXCEEDED.