# Event

A planning event: one block on a user's agenda, optionally linked to a kanban task so time can be logged against it. An event is either a one-off or the master of a recurring series, in which case the recurrence fields describe how its occurrences are generated. The occurrences are rendered from those fields and are not rows of their own, except where one was separated in plnnrly.

## Used by
- GET /api/v2/events: List events (EventList)
- POST /api/v2/events: Create an event (Event)
- GET /api/v2/events/{event}: Read an event (Event)
- PATCH /api/v2/events/{event}: Update an event (Event)
- POST /api/v2/events/{event}/actions/restore: Restore a deleted event (Event)

## Event fields
- id (integer, required): Unique identifier.
- user_id (integer, required, server-assigned): Whose agenda the event is on. Always the authenticated user at creation time; not writable.
- task_id (integer or null, required): Kanban task this event is planned against, or `null` for a plain calendar block. Only an event with a task can have time logged on it.
- parent_event_id (integer or null, required, server-assigned): Master event, when this row is a separated occurrence of a recurring series. Set by the server; not writable.
- occurrence_date (date (YYYY-MM-DD) or null, required, server-assigned): The date of the series occurrence this row replaces. Set by the server; not writable.
- start (timestamp (YYYY-MM-DDThh:mm:ssZ), required): When the event starts. RFC 3339 UTC.
- end (timestamp (YYYY-MM-DDThh:mm:ssZ), required): When the event ends. RFC 3339 UTC.
- title (string ≤ 255, required): Event title, as shown on the calendar tile.
- description (html or null, required, detail only): Free-text description, authored in the rich editor. HTML, sanitised on the way in and on the way out; `@`-mention spans are preserved, and changing them is what notifies the people mentioned.
- is_all_day (boolean, required): Whether the event occupies whole days rather than a time range. An all-day event is measured against the owner's working week rather than against start and end.
- is_recurring (boolean, required): Whether this row is the master of a recurring series. When `true`, the recurrence fields describe how occurrences are generated.
- recurrence_interval (integer or null, required): How many frequency units pass between occurrences: 2 with a weekly frequency is every other week.
- recurrence_frequency (string or null, required): The unit the series repeats in.
- recurrence_pattern (string or null, required): How a monthly or yearly series positions its occurrence within the month. Ignored for a daily or weekly frequency.
- recurrence_start (timestamp (YYYY-MM-DDThh:mm:ssZ) or null, required): First moment the series may generate an occurrence.
- recurrence_end (timestamp (YYYY-MM-DDThh:mm:ssZ) or null, required): Last moment the series may generate an occurrence; `null` for an open-ended series.
- selected_weekdays (array of string or null, required, detail only): Weekdays a recurring event falls on. Applies to a weekly frequency; ignored otherwise.
- recurrence_exceptions (array of string or null, required, detail only): Dates on which this recurrence does not occur. plnnrly adds one whenever a single occurrence is separated or deleted.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- deleted_at (timestamp (YYYY-MM-DDThh:mm:ssZ) or null, required): When the event was deleted, or `null` while it is live. Reach a deleted event with `trashed=with` and undo it with POST `events/{event}/actions/restore`.
- user (Ref or UserSummary, required): The user whose agenda the event is on. Renders as an `{"id": N}` reference unless expanded.
- links (EventLinks, required)
  - self (url, required): The canonical URI of this record.

Only on `?view=detail`: description, selected_weekdays, recurrence_exceptions

## Variants

### EventList

What a collection returns, and what `?view=summary` returns on a single record.

20 fields.
Omits: description, selected_weekdays, recurrence_exceptions

### EventSummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

3 fields.
Omits: user_id, task_id, parent_event_id, occurrence_date, end, description, is_all_day, is_recurring, recurrence_interval, recurrence_frequency, recurrence_pattern, recurrence_start, recurrence_end, selected_weekdays, recurrence_exceptions, created_at, updated_at, deleted_at, user, links

### EventLinks

The `links` object on this resource.

Keys: self

## Columns deliberately not published
- client_id: The id plnnrly's agenda gives a dropped tile so a repeated create returns the stored event instead of a second one. Only the agenda uses it; an API client neither reads nor sends it.

## Example
```json
{
  "id": 1,
  "user_id": 1,
  "task_id": 1,
  "parent_event_id": 1,
  "occurrence_date": "2026-03-04",
  "start": "2026-03-03T09:00:00Z",
  "end": "2026-03-03T10:30:00Z",
  "title": "Design review",
  "description": "<p>…</p>",
  "is_all_day": false,
  "is_recurring": false,
  "recurrence_interval": 1,
  "recurrence_frequency": "day",
  "recurrence_pattern": "day_of_month",
  "recurrence_start": "2026-03-04T09:15:00Z",
  "recurrence_end": "2026-03-04T09:15:00Z",
  "selected_weekdays": [
    "monday"
  ],
  "recurrence_exceptions": [
    "2026-03-04"
  ],
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "deleted_at": "2026-03-04T09:15:00Z",
  "user": {
    "id": 1
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1"
  }
}
```