Calendar Service API Reference¶

The calendar-service manages availability templates, rules, and calculations for partner services.

Base URL: http://<host>:3000/api (Internal) or /api/calendar (Public Gateway)

Templates¶

Create Template¶

POST /templates

Create a new availability template.

Body:

{
  "partner_id": "uuid",
  "name": "Summer Season",
  "is_default": false,
  "timezone_mode": "utc",
  "timezone": "Atlantic/Azores",
  "rules": [
    {
      "type": "AVAILABLE",
      "freq": "WEEKLY",
      "by_day": ["MO", "TU", "WE", "TH", "FR"],
      "time_ranges": [
        { "start_time": "09:00", "end_time": "17:00" }
      ]
    }
  ]
}

List Templates¶

GET /templates?partner_id=<uuid>

Returns all templates for a partner.

Get Template¶

GET /templates/:id

Returns details of a specific template.

Update Template¶

PATCH /templates/:id

Update name, default status, or rules.

Delete Template¶

DELETE /templates/:id

Removes a template. Fails if bound to active services.

Service Bindings¶

Bind Service¶

POST /bindings

Link a service to a template.

Body:

{
  "service_id": "uuid",
  "template_id": "uuid",
  "mode": "LINKED"
}

Get Binding¶

GET /bindings?service_id=<uuid>

Get the current template binding for a service.

Delete Binding¶

DELETE /bindings?service_id=<uuid>&template_id=<uuid>

Unlink a service from a template.

Exceptions¶

Exceptions are atomic, single-day overrides that modify availability. Each exception targets one date and can be full-day or time-ranged.

Create Exception¶

POST /exceptions

Body:

{
  "scope": "SERVICE",
  "partner_id": "uuid",
  "service_id": "uuid",
  "reason": "Christmas Holiday",
  "availability_type": "UNAVAILABLE",
  "is_full_day": true,
  "exception_date": "2026-12-25"
}

Field	Type	Required	Description
`scope`	`SERVICE` \| `PARTNER`	✅	Exception scope
`partner_id`	UUID	✅	Partner ID
`service_id`	UUID	When `scope=SERVICE`	Target service
`template_id`	UUID	Optional	Target template
`reason`	string	Optional	Human-readable reason
`availability_type`	`UNAVAILABLE` \| `AVAILABLE`	Optional (default: `UNAVAILABLE`)	Exception type
`is_full_day`	boolean	Optional (default: `true`)	Full day or time range
`exception_date`	DATE (`YYYY-MM-DD`)	✅	Target date
`start_time`	TIME (`HH:mm`)	When `is_full_day=false`	Start time
`end_time`	TIME (`HH:mm`)	When `is_full_day=false`	End time

Create Batch¶

POST /exceptions/batch

Creates multiple single-day exceptions with a shared batch_id.

Body:

{
  "scope": "SERVICE",
  "partner_id": "uuid",
  "service_id": "uuid",
  "reason": "Holiday week",
  "is_full_day": true,
  "dates": ["2026-12-23", "2026-12-24", "2026-12-25"]
}

List Exceptions¶

GET /exceptions?service_id=<uuid> — Service-scoped exceptions GET /exceptions?partner_id=<uuid> — All partner exceptions GET /exceptions?template_id=<uuid> — Template-scoped exceptions

Update Exception¶

PATCH /exceptions/:id

Updatable fields: reason, exception_date, availability_type, is_full_day, start_time, end_time.

Delete Exception¶

DELETE /exceptions/:id

Delete Batch¶

DELETE /exceptions/batch/:batchId

Removes all exceptions sharing the same batch_id.

Availability & Simulation¶

Get Availability¶

GET /services/:id/availability

Calculate available time slots for a specific range. Exceptions are automatically applied.

Query Params: - from: ISO Date String (Start) - to: ISO Date String (End)

Response:

[
  {
    "start": "2023-10-25T09:00:00Z",
    "end": "2023-10-25T17:00:00Z"
  }
]

Simulate Availability¶

POST /simulation

Test availability rules without persisting them.

Body:

{
  "service_id": "uuid",
  "start": "2023-10-25T00:00:00Z",
  "end": "2023-10-26T00:00:00Z",
  "rules": [...],
  "exceptions": [
    {
      "exception_date": "2023-10-25",
      "is_full_day": false,
      "start_time": "12:00",
      "end_time": "13:00",
      "availability_type": "UNAVAILABLE"
    }
  ]
}