API reference

GET/v1/calendars

Every calendar, with its rules, revision and coverage

Needs a Keycloak token or an API key.

• 200 The calendars in the dataset release. CalendarList
• 400 `validation_failed`: the request is malformed.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.
• 503 `dataset_unavailable`: no dataset release has been cut yet.

GET/v1/calendars/{id}/days/{date}

Whether a date is a business day on one calendar, and why

Needs a Keycloak token or an API key.

• 200 The answer and the entry or rule that decided it. DayAnswer
• 400 `validation_failed`: the request is malformed.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.
• 404 `unknown_calendar`: no calendar has this ID.
• 422 `out_of_range`: a date is outside a calendar's source coverage.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.
• 503 `dataset_unavailable`: no dataset release has been cut yet.

GET/v1/calendars/{id}/days

Answer every date in a range for one calendar

Each covered date from `from` to `to` (both inclusive, at most 500 days), answered as `GET /v1/calendars/{id}/days/{date}` would, with the nearest business days either side. Dates outside the calendar's coverage are left out. With no `from`, the range starts on 1 January of the current year; with no `to`, it ends 90 days after today. Both use the calendar's time zone, and `today` is the calendar's date now.

Needs a Keycloak token or an API key.

• 200 The covered days in the range, in date order. DayRange
• 400 `validation_failed`: the request is malformed.
• 404 `unknown_calendar`: no calendar has this ID.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.
• 503 `dataset_unavailable`: no dataset release has been cut yet.

GET/v1/calendars/{id}/closures

The closures on one calendar between two dates

Closures are the dates an entry closes (weekends aren't listed). The range is at most 731 days, and all of it must be within the calendar's coverage.

Needs a Keycloak token or an API key.

• 200 The closures in date order. ClosureList
• 400 `validation_failed`: the request is malformed.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.
• 404 `unknown_calendar`: no calendar has this ID.
• 422 `out_of_range`: a date is outside a calendar's source coverage.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.
• 503 `dataset_unavailable`: no dataset release has been cut yet.

POST/v1/business-days/check

Whether a date is a business day on several calendars combined

Needs a Keycloak token or an API key.

Body: DayRequest

• 200 The combined answer, with each calendar's answer as evidence. DayAnswer
• 400 `validation_failed`: the request is malformed.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.
• 404 `unknown_calendar`: no calendar has this ID.
• 422 `out_of_range`: a date is outside a calendar's source coverage.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.
• 503 `dataset_unavailable`: no dataset release has been cut yet.

POST/v1/business-days/add

Move a number of business days from a date

Moves `days` business days from `date`, backwards when negative. `date` itself doesn't count, and 0 returns `date`. Every day passed over is listed in `skipped`, in the order met, with why it isn't a business day.

Needs a Keycloak token or an API key.

Body: AddRequest

• 200 Where the move landed. Shifted
• 400 `validation_failed`: the request is malformed.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.
• 404 `unknown_calendar`: no calendar has this ID.
• 422 `out_of_range`: a date is outside a calendar's source coverage.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.
• 503 `dataset_unavailable`: no dataset release has been cut yet.

POST/v1/business-days/next

The first business day after a date

Never `date` itself; the same as adding one business day.

Needs a Keycloak token or an API key.

Body: DayRequest

• 200 The next business day. Shifted
• 400 `validation_failed`: the request is malformed.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.
• 404 `unknown_calendar`: no calendar has this ID.
• 422 `out_of_range`: a date is outside a calendar's source coverage.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.
• 503 `dataset_unavailable`: no dataset release has been cut yet.

GET/v1/changes

List published calendar changes using keyset pagination

Needs a Keycloak token or an API key.

• 200 Changes ordered by publication instant and stable event ID. ChangePage
• 400 `validation_failed`: the request is malformed.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.

POST/v1/receipts/verify

Verify a receipt against the configured public key history

Needs a Keycloak token or an API key.

Body: Receipt

• 200 `valid` is false for a modified payload, signature, ID or unknown key. ReceiptVerification
• 400 `validation_failed`: the request is malformed.

GET/.well-known/zeitwide-keys.json

Public Ed25519 verification keys and validity intervals

Open to anyone, no key needed.

• 200 Current and retained historical public keys. ReceiptKeySet

GET/.well-known/oauth-protected-resource/mcp

OAuth protected resource metadata for the MCP endpoint

Open to anyone, no key needed.

• 200 MCP resource identifier, authorization server, and supported bearer method. object

GET/v1/account/api-keys

List API keys for the authenticated account

Needs a Keycloak token or an API key.

• 200 Up to 100 key metadata rows. Secret values are never returned by this operation. array of ApiKeySummary
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.

POST/v1/account/api-keys

Create an API key and return its value once

Needs a Keycloak token or an API key.

Body: object

• 201 The key value is present only in this response. CreatedApiKey
• 400 `validation_failed`: the request is malformed.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.
• 409 API key account limit reached or this idempotency key was already used.

DELETE/v1/account/api-keys/{id}

Revoke one API key belonging to the authenticated account

Needs a Keycloak token or an API key.

• 204 The key was revoked or was already absent.
• 401 `invalid_api_key`: the key is unknown, malformed or revoked.

GET/v1/account/webhooks

List webhook subscriptions without their signing secrets

Needs a Keycloak token or an API key.

• 200 Up to 100 active subscriptions for the authenticated account. array of WebhookSubscription
• 401 `unauthorized`: authentication is required.

POST/v1/account/webhooks

Create a webhook and return its signing secret once

Needs a Keycloak token or an API key.

Body: WebhookConfiguration

• 201 The generated signing secret is returned only in this response. CreatedWebhook
• 400 `validation_failed`: the request is malformed.
• 401 `unauthorized`: authentication is required.
• 409 `idempotency_key_reused`: this key was already used.
• 429 `rate_limited`: too many requests; try again after `Retry-After` seconds.

PUT/v1/account/webhooks/{id}

Update a webhook URL and event filter

Needs a Keycloak token or an API key.

Body: WebhookConfiguration

• 200 The updated subscription; its signing secret remains hidden. WebhookSubscription
• 400 `validation_failed`: the request is malformed.
• 404 `not_found`: no active resource has this ID.

DELETE/v1/account/webhooks/{id}

Disable a webhook and abandon its pending deliveries

Needs a Keycloak token or an API key.

• 204 The subscription was disabled or was already absent.

POST/v1/account/webhooks/{id}/test

Send a signed test event to a webhook

Needs a Keycloak token or an API key.

• 200 Test event delivery result; receiver response bodies are discarded. WebhookTestResult
• 404 `not_found`: no active resource has this ID.

GET/v1/account/alert-rules

List the account's alert rules

Alert rules say which published changes matter to the account. While an account has at least one rule, its webhooks receive only changes that match a rule (and the webhook's own event filter); with no rules, webhooks receive every change.

Needs a Keycloak token or an API key.

• 200 Up to 50 rules, newest first. array of AlertRule
• 401 `unauthorized`: authentication is required.

POST/v1/account/alert-rules

Create an alert rule

Needs a Keycloak token or an API key.

Body: AlertRuleConfiguration

• 201 The created rule. AlertRule
• 400 `validation_failed`: the request is malformed.
• 401 `unauthorized`: authentication is required.
• 409 `alert_rule_limit_reached` or `idempotency_key_reused`.

PUT/v1/account/alert-rules/{id}

Replace an alert rule

Needs a Keycloak token or an API key.

Body: AlertRuleConfiguration

• 200 The updated rule. AlertRule
• 400 `validation_failed`: the request is malformed.
• 404 `not_found`: no active resource has this ID.

DELETE/v1/account/alert-rules/{id}

Delete an alert rule

Needs a Keycloak token or an API key.

• 204 The rule was deleted or was already absent.

GET/v1/admin/candidates

List candidate changes for review, urgent first

Pending candidates sort urgent first (under 14 days' notice), then by date. Requires the Keycloak role `reviewer`.

Needs a Keycloak token or an API key.

• 200 Candidates with the requested status. CandidateList
• 401 `unauthorized`: authentication is required.
• 403 `forbidden`: the caller lacks the required role.

GET/v1/admin/candidates/{id}

One candidate with the current entry and every supporting snapshot

Needs a Keycloak token or an API key.

• 200 The candidate and its evidence. CandidateDetail
• 401 `unauthorized`: authentication is required.
• 403 `forbidden`: the caller lacks the required role.
• 404 `not_found`: no active resource has this ID.

POST/v1/admin/candidates/{id}/decision

Approve or reject a pending candidate

Records the reviewer (the token's subject), the reason and the time. The pipeline publishes an approved candidate on its next run, in one transaction; no answer changes before then.

Needs a Keycloak token or an API key.

Body: CandidateDecision

• 200 The candidate after the decision. CandidateDetail
• 400 `validation_failed`: the request is malformed.
• 401 `unauthorized`: authentication is required.
• 403 `forbidden`: the caller lacks the required role.
• 404 `not_found`: no active resource has this ID.
• 409 `candidate_not_pending`: someone already decided this candidate.

GET/v1/admin/sources

Freshness and failures for every source

Needs a Keycloak token or an API key.

• 200 Every source with its check state. SourceHealthList
• 401 `unauthorized`: authentication is required.
• 403 `forbidden`: the caller lacks the required role.

GET/v1/admin/releases

Dataset releases, newest first

Needs a Keycloak token or an API key.

• 200 The most recent releases. ReleaseList
• 401 `unauthorized`: authentication is required.
• 403 `forbidden`: the caller lacks the required role.

AddRequest

AlertRule

AlertRuleConfiguration

ApiKeySummary

Basis

`published` by the operator, or `projected` by Zeitwide from other sources.

published | projected

Calendar

CalendarDay

One calendar's answer for one date, and what decided it.

CalendarId

string

CalendarList

CalendarRevisions

Each calendar's revision at `as_of`, by calendar ID.

object

Candidate

CandidateDecision

CandidateDetail

CandidateList

CandidateSnapshot

One source snapshot that supports the candidate, and what the parser read from it.

CandidateStatus

pending | approved | rejected | published

Change

ChangePage

ChangeType

closure_added | closure_removed | closure_changed | basis_changed

Closure

ClosureList

Combine

`all_open`: every calendar is open. `any_open`: at least one is.

all_open | any_open

Corroboration

`corroborated`: a second, independent source agrees.

single_source | corroborated

Coverage

The dates the calendar can answer for. `years`: from `from` to `to`, both inclusive. `unlimited`: any date (the calendar closes on no holiday). `none`: nothing recorded yet, so no date.

CreatedApiKey

CreatedWebhook

WebhookSubscription and object

DatasetRelease

string

DayAnswer

DayRange

DayRequest

EntryState

OutboxDrainResult

Problem

RFC 9457 problem details.

RangeDay

Receipt

ReceiptKeySet

ReceiptPayload

ReceiptPublicKey

ReceiptVerification

Release

ReleaseList

Shifted

SkippedDay

Source

A snapshot of an official source that backs an entry.

SourceHealth

SourceHealthList

WebhookConfiguration

WebhookSubscription

WebhookTestResult