POST/v1/me/calendar/events

Creates one appointment in a calendar this account may write in. Whether the guests are told is a field, not a side effect: correcting your own typo should not put mail in six inboxes.

Request

Field	Required	Description
`calendar_id`	yes	The `id` of a calendar with `write` or `manage` access, such as `cal_r4d8h2m6t9w3k7nb`
`title`	yes
`starts_at`	yes	ISO 8601
`ends_at`	yes	ISO 8601, not before `starts_at`
`all_day`	no
`description`	no
`location`	no
`color`	no	Overrides the calendar's own colour
`recurrence_rule`	no	An `RRULE` without the prefix, for example `FREQ=WEEKLY;BYDAY=MO`. `FREQ`, `INTERVAL`, `BYDAY`, `COUNT` and `UNTIL` are understood
`conference_url`	no	The provider is worked out from the link, whatever you call it
`guests[]`	no	Email addresses
`reminders[]`	no	`{ "minutes_before": 10, "channel": "in_app" }`, channel `in_app` or `email`, at most five
`tag_ids[]`	no	Labels of this workspace, by `id` from the label list, at most twenty. An id from another workspace is refused with `validation_failed`. The list comes back whole on every appointment
`notify`	no	Send the guests a proper invitation. Needs a verified sending address on the environment

Send the same Idempotency-Key on a retry

Every POST needs an Idempotency-Key header, and a retry that carries the same one gets the first answer back rather than making a second appointment. See idempotency.

curl -X POST https://api.proppertrading.com/v1/me/calendar/events \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Idempotency-Key: 8f14e45f-ea0d-4d1f-9c4b-3e11f0f2c0a1" \
  -H "Content-Type: application/json" \
  -d '{
    "calendar_id": "cal_r4d8h2m6t9w3k7nb",
    "title": "Intro call",
    "starts_at": "2026-08-25T13:00:00Z",
    "ends_at": "2026-08-25T13:30:00Z",
    "guests": ["[email protected]"],
    "reminders": [{ "minutes_before": 10, "channel": "in_app" }],
    "tag_ids": ["ctag_f7k3w9n2b5r8m4tx"],
    "notify": true
  }'

Response

201, with the appointment as the list returns it.

{
    "data": {
        "id": "evt_w3n8c5h2r7d4j9ps",
        "object": "calendar_event",
        "occurrence_start": null,
        "calendar_id": "cal_r4d8h2m6t9w3k7nb",
        "title": "Intro call",
        "starts_at": "2026-08-25T13:00:00+00:00",
        "ends_at": "2026-08-25T13:30:00+00:00",
        "all_day": false,
        "status": "confirmed",
        "source": "manual",
        "is_recurring": false,
        "tags": [{ "id": "ctag_f7k3w9n2b5r8m4tx", "name": "Onboarding", "color": "emerald" }],
        "can_write": true
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}

Errors

Status	Code	Meaning
400	`missing_idempotency_key`	The `Idempotency-Key` header was not sent
400	`validation_failed`	A field was missing or wrong. `error.param` names it
403	`insufficient_scope`	This device does not hold `calendar:write`
403	`calendar_read_only`	The account may read that calendar but not write in it, or it is a followed calendar, which nobody writes in
404	`resource_not_found`	No such calendar here

Create an appointment

Request

Response

Errors