🗓️ REST API: Calendar

The complete usage guide for the standalone Calendar module of the REST API — the shared team calendar's events and categories. Mirrors the interactive documentation at System → API → Documentation (with its live "Try it" tester).

[!NOTE] New to the API? The basics table on REST API: Tickets covers base URL, authentication, the response envelope, error codes, rate limits and PATCH semantics — identical across all modules. Except one thing here — read the datetime warning below.

What's distinctive about Calendar:

🕐 Naive server-local datetimes	Unlike every other module (ISO 8601 UTC with Z), calendar events are stored without timezone conversion — that's how the UI writes them and how the ICS feed interprets them. This resource accepts and returns naive YYYY-MM-DD HH:MM:SS values and rejects Z/offset designators with a 422, so you can't accidentally shift every meeting by an hour.
🤖 Generated events are read-only	Rows with source = "asset_warranty" are owned by the warranty sync, which wipes and regenerates them wholesale. The API shows you source on reads (the internal endpoints don't return it at all!) and answers 409 to updates/deletes on generated rows — tighter than the UI, where an edit silently evaporates on the next sync. You can never set source on create.
📡 The ICS feed already exists	For subscribing Outlook/Google/Apple Calendar, use the built-in token-authenticated feed (api/calendar/feed.php?token=…, issued per-analyst from the Calendar UI). The REST API is for programmatic event management — creating maintenance windows from a pipeline, syncing from another system.
🌍 One shared calendar	Install-wide, no per-analyst or per-company calendars — matching the module.

---

🚀 Quick start

A deployment pipeline booking its maintenance window:

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"

curl -X POST "$B/calendar/events" -H "$K" -H "Content-Type: application/json" -d '{
  "title": "Maintenance window — release 2.4",
  "start_at": "2026-07-05 06:00:00",
  "end_at":   "2026-07-05 08:00:00",
  "category_id": 1,
  "location": "Production",
  "description": "Core switch SFP replacement (CHG-0011)."
}'

---

🗓️ Events

🟢 GET /calendar/events — list in a window   🔑 calendar_events.read

Provide a from/to window (the UI's exact three-branch overlap logic — an event matches if it starts in, ends in, or spans the window; from inclusive, to exclusive) — or contract_id, or all=true.

Parameter	Description
from / to	Naive local datetimes — 2026-07-01 00:00:00 (T separator OK, date-only OK)
contract_id	Events linked to a contract (window optional)
all	true = everything (paginate!)
category_id	One category — or categories=1,2,3 for several
source	manual (source is null) or a generator name like asset_warranty
q	Search title and location
page / per_page	Pagination — default 1 / 25, max 100

The event shape:

{ "id": 12, "title": "Maintenance window — release 2.4",
  "description": "Core switch SFP replacement (CHG-0011).",
  "category": { "id": 1, "name": "Maintenance", "color": "#ef6c00" },
  "start_at": "2026-07-05 06:00:00", "end_at": "2026-07-05 08:00:00",
  "all_day": false, "location": "Production",
  "contract_id": null,
  "source": null,
  "created_by": { "id": 1, "name": "Administrator" },
  "created_at": "2026-07-03 16:56:41", "updated_at": "2026-07-03 16:56:41" }

source: null = a manual event you can edit. source: "asset_warranty" = generated (read-only; created_by is null — the sync's sentinel).

🔵 POST /calendar/events — create   🔑 calendar_events.create

Field	Required	Description
title	✅	Event title
start_at	✅	Naive local datetime
end_at		Defaults to start_at; can't be before it (422)
all_day		Boolean
description / location		Details
category_id		Validated (422 on unknown — friendlier than the UI's raw FK error)
contract_id		Link to a contract (validated)

Always creates a manual event (source can never be set). Returns 201.

🟢 GET /calendar/events/{id}   🔑 calendar_events.read · 🟠 PATCH /calendar/events/{id}   🔑 calendar_events.update

Everything creatable is patchable; title and start_at can't be cleared.

[!WARNING] A generated event (source set) answers 409 to PATCH — "generated by the 'asset_warranty' sync and read-only — it would be recreated on the next sync anyway."

🔴 DELETE /calendar/events/{id}   🔑 calendar_events.delete

Deletes a manual event. Generated events answer 409 — retire them by clearing the asset's warranty date (or the warranty-surface setting) and letting the sync take them away.

---

🎨 Categories

🟢 GET /calendar-categories   🔑 reference.read

All categories with colour and live event counts (category management stays in Calendar → Settings):

{ "data": [ { "id": 1, "name": "Maintenance", "color": "#ef6c00",
              "description": null, "is_active": true, "event_count": 4 } ] }

---

🧪 Worked example: today's ops briefing

A read-only key (calendar_events: read + reference: read) posting the day's schedule to chat:

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"
TODAY=$(date +%F)

curl -s -H "$K" "$B/calendar/events?from=$TODAY%2000:00:00&to=$TODAY%2023:59:59&per_page=50" \
  | jq -r '.data[] | "\(.start_at[11:16])  [\(.category.name // "-")]  \(.title)\(if .source then " 🤖" else "" end)"'

And the automation direction — clearing a cancelled maintenance window by title:

ID=$(curl -s -H "$K" "$B/calendar/events?all=true&q=release+2.4" | jq -r '.data[0].id')
curl -s -X DELETE "$B/calendar/events/$ID" -H "$K"

---

Under the hood: REST API — How It Works · Other modules: Tickets · Assets · Problems · Changes · Knowledge · Tasks · CMDB · Contracts · Keys & permissions: System → API (System module) · Module docs: Calendar.