Calendar: Rules

Base URL: $BUSINESS_API

List recurring calendar rules

Logs

GET /calendar/rules

Lists the tenant's recurring holiday rules (fixed yearly date, nth or last weekday of a month, or an offset from Western or Orthodox Easter) in a data array without pagination. Each rule carries its observed-day policy, validity window and source. Rules that come from a followed template are not listed here. Requires automations:read.

Parameters

area_idstring · query · optional

Service area id; when set, the list holds that area's rules plus the tenant-wide rules that have no area, and when omitted it holds every rule of the tenant.

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Calendar rules

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/calendar/rules" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Calendar rules

Add a recurring calendar rule

Logs

POST /calendar/rules

Creates a recurring rule that marks a date every year and returns it with 201. fixed_yearly needs month 1-12 and day 1-31; nth_weekday and last_weekday need month and weekday 0-6 (position picks the nth week, -1 the last); easter_offset needs easter_kind western or orthodox plus a day offset. observed (none, next, previous or nearest) moves the date to a working day when it falls on a day off, at least one of name_pt or name_en is required, and valid_from/valid_to are optional YYYY-MM-DD bounds. Invalid combinations return 400. Requires automations:write.

Body application/json

kindstring · required

one of fixed_yearly, nth_weekday, last_weekday, easter_offset

monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring · optional
valid_tostring · optional
name_ptstring · required
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional

Returns

201 Created rule

Errors 400

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X POST "$BUSINESS_API/calendar/rules" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "fixed_yearly",
  "month": 1,
  "day": 1,
  "weekday": 0,
  "position": 1,
  "easter_kind": "western",
  "easter_offset": 1,
  "observed": "none",
  "valid_from": "1975-01-01",
  "valid_to": "2030-12-31",
  "name_pt": "name pt",
  "name_en": "name en",
  "kind_of_day": "holiday",
  "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
  "source_ref": "source ref"
}'
Response 201

Created rule

Update fields of a recurring calendar rule

Logs

PATCH /calendar/rules/{id}

Changes only the fields sent on a recurring rule and returns the updated rule. The merged rule is validated again with the same checks as on creation, so a change that leaves it inconsistent (for example switching to easter_offset without easter_kind) returns 400. The rule's area cannot be changed. Returns 404 when the rule is not in this tenant. Requires automations:write.

Parameters

idstring · path · required

Id of the calendar rule to update (prefix crl).

Body application/json

kindstring · optional

one of fixed_yearly, nth_weekday, last_weekday, easter_offset

monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring · optional
valid_tostring · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

Returns

200 Updated rule

Errors 404

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X PATCH "$BUSINESS_API/calendar/rules/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "fixed_yearly",
  "month": 1,
  "day": 1,
  "weekday": 0,
  "position": 1,
  "easter_kind": "western",
  "easter_offset": 1,
  "observed": "none",
  "valid_from": "2026-11-19",
  "valid_to": "2026-11-19",
  "name_pt": "name pt",
  "name_en": "name en",
  "kind_of_day": "holiday"
}'
Response 200

Updated rule

Remove a recurring calendar rule

Logs

DELETE /calendar/rules/{id}

Deletes a recurring rule and returns 204 with no body; dates it produced stop counting as days off for schedules evaluated afterwards. Returns 404 when the rule is not in this tenant. Requires automations:write.

Parameters

idstring · path · required

Id of the calendar rule to delete (prefix crl).

Returns

204 Deleted

Errors 404

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X DELETE "$BUSINESS_API/calendar/rules/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Deleted