How to do the thing you came to do.

1. Subscribe

1. Go to Subscribe and enter your email address.
2. Choose the traditions you want to see. You do not have to take all of them, and you can change this later.
3. Choose your country. This matters more than it looks: dates that depend on a moon sighting genuinely differ between countries, and this is how you get the ones your own community keeps.

2. Confirm

1. We send one email. Nothing else is ever sent until you confirm.
2. Follow the link in it. That completes the sign-up and shows your calendar link.
3. Copy the link. It is yours alone. Anyone who has it can see your calendar, so treat it like a password.

3. Add it to your calendar

You are subscribing to a feed, not importing a file. That distinction matters: a subscription keeps itself up to date, so when a date is confirmed or moves, the entry you already hold changes rather than a second one appearing.

• Outlook — Calendar, then Add calendar, then Subscribe from web. Paste the link and give it a name.
• Google Calendar — in the left column find Other calendars, press the plus, choose From URL. Paste the link. Google refreshes on its own schedule, which can take up to a day.
• Apple Calendar — File, then New Calendar Subscription. Paste the link. Set Auto-refresh to every day.

Changing your mind

Every email we send carries a link to your subscription page. From there you can see your calendar link again, replace it if it has got out, change which traditions you see, or cancel. Cancelling stops the calendar link working as well as the email.

You will be sent one admin link. That link is the account: anyone holding it can add and remove people, so keep it somewhere your team keeps passwords rather than in a shared inbox.

Adding somebody

1. Open your admin link.
2. Type their work email address and press Add.
3. They receive their own confirmation email. Being added by you is not consent, so nothing reaches them until they confirm for themselves. Somebody who never confirms simply never receives anything, and still uses a seat until you remove them.
4. Once confirmed they have their own calendar link, their own country and traditions, and their own unsubscribe. What they see is theirs to choose.

When somebody leaves

• Remove takes their calendar away immediately and frees the seat for somebody else.
• Replace link is for when you want them to keep access but the link itself has been shared too widely. It issues a new one, stops the old one at once, and emails them to say so.

Running out of seats

Adding beyond your plan is refused and tells you how many are in use. Removed people do not count. If you need more, write to sales@beliefcalendar.app rather than opening a second account, so everyone stays on one bill.

Different countries

If your workforce is spread across countries, each person should choose their own. Two colleagues seeing different dates for the same festival is not a fault: a date that depends on a local sighting is genuinely different in Dubai and Manchester, and a single global date would be wrong for at least one of them.

The contract is published at openapi.json and browsable at the API documentation. Your key goes in an x-api-key header on every request.

Your first call

curl -H "x-api-key: YOUR_KEY" \
  "https://api.beliefcalendar.app/v1/observances?year=2026&region=GB"

What each operation is for

• /v1/observances — the dates. Needs either a year, or a from and a to. Pass a region or you will get the unresolved reckoning.
• /v1/changes — what has moved since a date you give it. This is how you keep a copy in step without refetching everything.
• /v1/regions and /v1/traditions — the identifiers to use in the calls above.
• /v1/coverage — what we do not compute. An empty list means no declared gaps today; poll it to learn of one the day it appears.
• /v1/feeds/{region}.ics — the same dates as a calendar file, if it is easier to hand your users a subscription than to build a view.
• /v1/feeds/{region}/cancel.ics — the same dates again, as a cancellation, for taking them back out of a calendar somebody imported them into. Pass the same tradition you passed on the way in.

What a cancellation can and cannot do

A calendar that subscribed to a feed needs no cancellation: drop the subscription and the dates go with it. A cancellation is for dates that wereimported, which are copies, and there the removing is done by the calendar application rather than by us. What each one does with a cancellation differs, and none of it is under our control.

We have measured it twice against iCloud and got very different answers. On 401 dates imported into an existing calendar and cancelled some time later, 235 were deleted outright, 95 were left showing as cancelled and 71 were untouched. On 6 dates imported and cancelled straight afterwards, one was deleted and five were left exactly as they were, not even marked.

So treat a cancellation as a partial measure that may achieve very little. Do not tell your users their calendar will be clean afterwards. We publish the endpoint because it costs a user nothing to try and sometimes does most of the work, not because it can be relied on.

If you control how your users add the calendar, the better answer is to avoid the situation: have them subscribe rather than import, or import into a new, empty calendar. Deleting that one calendar removes every date at once, and it is the only method that is quick and certain.

How the dates are checked

Every date is computed from the published rule rather than copied from anyone else’s list, and every week the results are compared with calendars kept independently of us: Hebcal, the Roman and Orthodox liturgical calendars, aladhan, a published Indian calendar, Hong Kong’s holidays, and the Jet Propulsion Laboratory for the positions of the sun and moon. The same check runs before any change to the calendar engine can be merged.

It earns its place. It has already found a fault nothing else could: every Hindu festival falling in an intercalary month was being computed a lunar month early, and the engine’s own tests all passed because they compared it with its own past output. Where we and an outside calendar disagree, one of us is wrong and we go and find out which.

What that does not give you is a specialist’s reading. No expert in these traditions has been through the calendar end to end, the checks are mechanical, and they cannot tell you whether a date matches how a particular community keeps it. Tell us when something is wrong and we correct it within five working days.

The one field not to ignore

Every observance carries confidence. A fixed date cannot move. A computed one comes from a published rule. An estimated one depends on a sighting or an announcement that has not happened yet, and displaying it as certain is the mistake this field exists to prevent. An announced one has been confirmed by a named authority for a named country.

Keeping a copy in step

1. Fetch the year once and store it.
2. Poll /v1/changes?since=YYYY-MM-DD daily with the date of your last successful sync.
3. Match on the observance id together with its year and region. That triple is the same identity the calendar feeds use, so a change you apply lines up with the entry a subscriber already holds.

Limits and keys

• Twenty requests a second, bursting to fifty, and 100,000 a month.
• A well-built integration needs very few: the dates change rarely, so poll /v1/changes daily rather than fetching the year repeatedly.
• Two keys can be live at once, so a rotation needs no downtime. Ask for the second, move across, then tell us to retire the first.
• A missing or wrong key is refused at the gateway with a 403 before it reaches our code.

A date changed

That is the service working. A date marked May vary is an estimate until the authority for your country announces it. When they do, we update the entry you already hold rather than sending a second one, so it changes in place.

A colleague sees a different date

Check which country each of you chose. Dates that depend on a sighting are genuinely different between countries, and both calendars can be right.

The calendar has stopped updating

Usually one of three things: the subscription was cancelled, mail to the address has been failing so we stopped sending, or the link was replaced and the old one retired. Open the link from any of our emails and the page will say which.

You think a date is wrong

Tell us at corrections@beliefcalendar.app and say which observance, which country, and what you believe the correct date is. If you can point at the authority that says so, we will act on it faster. We publish which authority each date came from precisely so this conversation is possible.

Every date on this site is computed from published rules rather than copied from anyone’s list, and no religious authority has reviewed it. The about page sets out what that means and what it does not.