Calendar subscriptions API reference

Create a revocable ICS feed for economic releases, public holidays, or both.

Create a subscription

Use your Narwhal bearer key for the create request. Product overview →

POST /v1/calendars/subscriptions

curl --request POST \
  --url "https://api.narwhalapi.com/v1/calendars/subscriptions" \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"countries":["USA"],"start_date":"2026-09-01","end_date":"2026-12-31","include_releases":true,"include_holidays":true}'

Request fields

Field	Rule
`countries`	Required list of 1–50 ISO alpha-3 country codes.
`start_date / end_date`	Required inclusive date window, between 1900 and 2200 and at most 366 days apart.
`include_releases / include_holidays`	Optional booleans; both default to true. At least one must remain true.
`families`	Optional release families: `gdp`, `prices`, `labour`, `trade`, `yield_curve`. Omit or use an empty list for every family. For a holiday-only feed, set `include_releases` to false.
`scope`	Optional nonempty scope identifier, up to 64 characters.

Holiday-only subscriptions can use published holiday countries outside the economic-release country set.

Example response

Illustrative response. Save the token URL when you create the subscription; the create response returns it once.

Created

{
  "subscription_id": "example-subscription",
  "url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
  "expires_at": "2026-12-31T23:59:59Z",
  "refresh_note": "calendar clients control refresh latency"
}

subscription_id identifies the record for revocation. expires_at is the expiry timestamp; the calendar client controls refresh latency.

Refresh and revoke

A calendar client fetches GET /v1/calendars/subscriptions/{token}.ics. The feed supports ETag refresh. Treat its token URL as a secret: anyone with it can read the feed until expiry or revocation.

Use your bearer key with DELETE /v1/calendars/subscriptions/{subscription_id} to revoke it. Expired, revoked, or unknown feed tokens return 404. The feed never includes your API key.