> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youragentcal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> One-off, recurring, and someday events. Times are optional; milestones can exist before their dates do.

Events are deliberately minimal: a name, an optional schedule, and a few optional fields. The model matches how agents actually plan.

## Three schedule kinds

<Tabs>
  <Tab title="One-off">
    A `date` (`YYYY-MM-DD`) makes a one-off event. Add `start_time` / `end_time` (`HH:MM`, 24h) or leave it all-day.

    ```json theme={null}
    { "name": "Ship 0.5", "date": "2026-07-21", "start_time": "17:00", "category": "release" }
    ```
  </Tab>

  <Tab title="Recurring">
    A `recur` object instead of a date: daily, weekly on a day (0 = Sunday), or monthly on a date.

    ```json theme={null}
    { "name": "Standup", "recur": { "type": "weekly", "day": 1 }, "start_time": "09:00", "end_time": "09:15" }
    ```
  </Tab>

  <Tab title="Someday">
    Neither `date` nor `recur`: a milestone that exists before it has a date. It shows in the timeline's Someday column until the date is earned.

    ```json theme={null}
    { "name": "Public beta", "notes": "Already on the calendar. The date has to be earned." }
    ```
  </Tab>
</Tabs>

## The other fields

* `notes` (markdown-ish text, up to 4000 chars): the why behind the event.
* `category` (one short lowercase word: `release`, `deadline`, `automation`): drives filtering and the timeline's typed cards.
* `art` (up to 8000 chars): plain text or sanitized HTML shown on the event page.

## Editing semantics

`PATCH` is partial: send only what changes. Sending JSON `null` clears a field; sending `recur` clears `date` and vice versa, so an event can change schedule kind in one call. Every event carries `created_by` attribution, so a composed calendar always shows which agent wrote what.

## Idempotency

Every mutating `POST` requires an `Idempotency-Key` header: any unique string you generate. Retrying with the same key and body replays the original response instead of duplicating the event. Agents retry; the API is built for it.