Events

Create an event in a calendar

Create a confirmed event, a tentative event, or a temporal hold. When creating a hold (status: "hold"), hold_expires_at is required and must be between 30 seconds and 15 minutes in the future. Holds auto-release at hold_expires_at; promote a hold to a confirmed event with PUT /v1/events/{id}/confirm before expiry.

post/v1/calendars/{cal_id}/events

Request

  • Base URL: https://api.chronary.ai
  • URL: https://api.chronary.ai/v1/calendars/{cal_id}/events
  • Auth: HTTP bearer

Path parameters

cal_idstring required

Calendar ID

Example:cal_01H9X4M2P5R8T6V0

Request body

titlestring required
start_timestring date-time required
end_timestring date-time required
descriptionstring
all_dayboolean
status'confirmed' | 'tentative' | 'cancelled' | 'hold'
metadataobject
remindersinteger[] nullable
recurrence_rulestring
hold_expires_atstring date-time
hold_priorityinteger

Response

Event created

idstring required
calendarIdstring required
orgIdstring required
titlestring required
descriptionstring nullable required
startTimestring date-time required
endTimestring date-time required
allDayboolean required
status'confirmed' | 'tentative' | 'cancelled' | 'hold' required
source'internal' | 'external_ical' required
metadataobject required
remindersinteger[] nullable required

Reminder offsets (minutes before start). Each fires an event.reminder webhook and emits a VALARM in the iCal feed. null = inherit the calendar default (then the system default of 10 min); [] = no reminders.

holdExpiresAtstring date-time nullable required

When set, the event is a tentative hold that auto-expires at this timestamp. Must be 30 seconds to 15 minutes in the future when creating a hold; the cap exists to keep held slots short enough that they do not block real scheduling for long.

holdPriorityinteger nullable required

Priority for conflict resolution. Higher values pre-empt lower-priority overlapping holds.

recurrenceRulestring nullable required

RFC 5545 RRULE subset (no "RRULE:" prefix) when this event is a recurring series master, e.g. "FREQ=WEEKLY;BYDAY=MO,WE;COUNT=12". Expansion is UTC-only. null = one-off event.

recurrenceExdatesstring[] required

ISO 8601 starts of individually cancelled occurrences (EXDATE).

recurringEventIdstring

Present only on expanded instances (expand=true): the id of the recurring series master this instance belongs to.

originalStartTimestring date-time

Present only on expanded instances: the occurrence start this instance was generated for.

deletedAtstring date-time nullable required
createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "id": "evt_01H9X4M2P5R8T6V0",
  "calendarId": "cal_01H9X4M2P5R8T6V0",
  "orgId": "org_01H9X4M2P5R8T6V0",
  "title": "Team standup",
  "description": "Daily sync meeting.",
  "startTime": "2025-01-20T09:00:00.000Z",
  "endTime": "2025-01-20T09:30:00.000Z",
  "status": "confirmed",
  "source": "internal",
  "metadata": {},
  "reminders": [
    10
  ],
  "recurrenceExdates": [],
  "recurringEventId": "evt_01H9X4M2P5R8T6V0",
  "originalStartTime": "2025-01-20T09:00:00.000Z",
  "external_sync": {
    "status": "not_configured"
  },
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.