:::endpoint 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      | Must be a calendar with `write` or `manage` access                                                                                                                |
| `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, 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                                                                          |

:::warning 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](/docs/api/idempotency).
:::

```bash
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": 12,
    "title": "Intro call",
    "starts_at": "2026-08-25T13:00:00Z",
    "ends_at": "2026-08-25T13:30:00Z",
    "guests": ["tom@acmefunded.com"],
    "reminders": [{ "minutes_before": 10, "channel": "in_app" }],
    "tag_ids": [4],
    "notify": true
  }'
```

## Response

`201`, with the appointment as [the list](/docs/api/calendar/events) returns it.

```json
{
    "data": {
        "id": 4482,
        "object": "calendar_event",
        "occurrence_start": null,
        "calendar_id": 12,
        "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": 4, "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 |
| 404    | `resource_not_found`      | No such calendar here                                  |