Events

title, start and end are the whole of what is required. Everything else has a default worth having.

curl https://pidgeon.ai/api/v1/identities/idn_4f2a1/calendar/events \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "title": "Invoice 4471",
  "start": "2026-11-03T09:00:00",
  "end": "2026-11-03T09:30:00",
  "timezone": "Europe/London",
  "location": "A call",
  "attendees": [{ "email": "priya@example.com", "name": "Priya Raman" }]
}'

timezone is optional and you should send it. Without one the calendar's default is used, which is right for an event somebody is adding to their own day and wrong for one you are scheduling on their behalf from a server somewhere else.

Inviting people

attendees is a list of addresses, up to 200. Adding them does not send anything: send_invites does, and it is a separate field because putting a meeting on a calendar and telling five people about it are different acts, and only one of them is undoable.

{
"title": "Invoice 4471",
"attendees": [{ "email": "priya@example.com" }],
"send_invites": true
}

With it, Pidgeon sends a real REQUEST from the mailbox — the kind Gmail and Outlook put an Accept button on. Invitations has what arrives and what comes back.

Changing one

PATCH the event. An omitted field survives, so a change to the title is a body with a title in it and nothing else.

PATCH /v1/identities/{id}/calendar/events/{eventId}

Two things are worth knowing before you write.

sequence rises only when the change is one attendees see — the time, the title, the place, the status, the list of people. Editing metadata is yours and does not bump it, so it does not make everybody's calendar client announce an update about nothing.

If-Match makes the write conditional. Every event carries an etag; send it back and the write is refused if somebody changed the event in between rather than silently overwriting them.

curl -X PATCH https://pidgeon.ai/api/v1/identities/idn_4f2a1/calendar/events/evt_8c21 \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H 'If-Match: "7c2ae104"' \
-H "Content-Type: application/json" \
-d '{ "location": "Moved to the big room" }'

A mismatch answers 412. Read the event again, decide what to do with the change somebody else made, and write again — the same shape as any other optimistic write.

Taking it off

DELETE removes the event. For one date of a repeating series it does something subtler, because the rule would simply generate that date again — Recurring events has mode and what each value means.