evt_

Events

Calendar events — the core resource. Normalized across providers with travel monitoring, recurrence, attendees, and ICS export.

Endpoints

POST /v1/events Create an event idempotent

GET /v1/events List events

GET /v1/events/{id} Retrieve an event

PATCH /v1/events/{id} Update an event idempotent

DELETE /v1/events/{id} Cancel or delete an event

POST /v1/events/{id}/notify_attendees Notify attendees idempotent

GET /v1/events/{id}/departure Get current departure

POST /v1/events/{id}/departure/recompute Force departure recomputation

Object shape

The event is the central resource. Every field is grounded in the production CalendarEvent model.

Field	Type		Description
id	string		Unique resource identifier, prefixed evt_.
object	string		Always event.
title	string	required	Event title.
description	string?		Long-form description. Markdown is not parsed.
category	string?		User-facing category. Common values: work, personal, health, education, social, travel.
color_hex	string?		Display color as a 7-character hex string.
start_time	datetime	required	ISO-8601 with explicit timezone offset.
end_time	datetime?		ISO-8601. Required unless all_day is true.
all_day	boolean		If true, time-of-day is ignored and the event spans 00:00–24:00 in timezone.
timezone	string		IANA timezone identifier. Default UTC.
location	object?		Destination location (see below).
from_location	object?		Optional explicit departure location. If null, ChronaPilot derives departure from user's last known position or home.
travel	object?		Travel modifiers — mode, parking_buffer_min, walk_buffer_min.
recurrence	object?		Either rule (RFC 5545 RRULE) or null.
attendees	array?		Array of {email, name, status} objects.
meeting	object?		Meeting metadata — type (online / in_person / both) and link.
source	object		Provenance — type (manual / google / microsoft), external_id, etag.
monitoring	object?		Live departure monitoring state. See Departure.
is_cancelled	boolean		True if cancelled by the user.
created_at	datetime		Resource creation time.
updated_at	datetime		Last mutation time.

Create an event

HTTP
POST /v1/events

Required fields: title, start_time. If you supply a location with an address, ChronaPilot geocodes asynchronously and begins computing a departure window.

Supports Idempotency-Key — strongly recommended.

Location object

Field	Type	Description
name	string	Friendly venue name.
address	string	Postal address (used for geocoding).
lat	number	Latitude. If absent and address is present, geocoded.
lng	number	Longitude.
type	string	place, address, or coords.

Travel object

Field	Type	Default	Description
mode	string	drive	One of drive, walk, transit.
parking_buffer_min	int	5	Minutes to budget for parking.
walk_buffer_min	int	3	Final walking minutes from parking to destination.

Retrieve an event

HTTP
GET /v1/events/{id}

Optionally expand: expand[]=monitoring, expand[]=connection, expand[]=invitations.

List events

HTTP
GET /v1/events

Filters: from (start time gte), to (end time lte), connection, calendar, category, livemode.

Update an event

HTTP
PATCH /v1/events/{id}

Partial. Supply only the fields you want to change. If start_time, end_time, or location change, monitoring re-computes within seconds and fires departure.updated.

Cancel / delete

HTTP
DELETE /v1/events/{id}

By default this soft-cancels the event (sets is_cancelled = true) and stops monitoring. Pass ?cascade=delete_in_source to also delete the event from the connected provider calendar.

Notify attendees

HTTP
POST /v1/events/{id}/notify_attendees

Sends an ICS-attached email plus push notifications to attendees who are also ChronaPilot users. Body:

JSON
{
  "type": "late",
  "delay_minutes": 15,
  "message": "Running 15 minutes behind, sorry."
}

Field	Type	Description
type	string	required — one of late, cancelled, rescheduled.
delay_minutes	integer?	When type=late. Estimated lateness; surfaces in the notification copy.
message	string?	Custom note appended to the notification.

Internally backed by the AttendeeNotification model and mirrors the notify_attendees voice tool.

Recurrence

ChronaPilot uses RFC 5545 RRULE strings. Supply a recurrence.rule on create and the event becomes a recurrence master.

Field	Type	Description
recurrence.rule	string?	RRULE — e.g. FREQ=WEEKLY;BYDAY=MO.
recurrence.parent_id	string?	Read-only. Set on instances of a recurring series; points to the master.

Behavioral rules:

Individual occurrences are accessible via GET /v1/events?recurrence_parent=evt_…&from=…&to=…. Occurrences are materialized lazily — a series's first 90 days are pre-expanded, rest expand on read.
PATCH on an instance forks it from the series. The forked instance retains a recurrence.parent_id pointer but its other fields are independent of the master.
PATCH on the master rewrites every future occurrence that has not been forked.
DELETE on an instance soft-cancels just that instance. DELETE on the master with ?scope=series cancels the master and all future occurrences.

Hard delete

HTTP
DELETE /v1/events/{id}?permanent=true

Hard-deletes the event from ChronaPilot. Used for GDPR right-to-erasure flows. Cannot be combined with cascade=delete_in_source — call delete-in-source first, then hard-delete locally. Returns 204 No Content.

Reference implementation

This resource is backed by the CalendarEvent entity (/src/Preeminent.ChronaPilot.Shared/Models/CalendarEvent.cs) and the endpoints under /src/Preeminent.ChronaPilot.Api/Endpoints/Events/.