# Create an appointment

Create an appointment on the caller's calendar.

Saves the appointment on the caller's calendar. Guests who are added get an invite on their own calendar, with status `invited`. The caller cannot name another address as the owner.

The end is after the start. A range that fails that check is `400` with `{ "error": "…" }`.

## Authentication

`Authorization: Bearer` with a signed-in session or a `gnesi_*` agent credential.

## Body

`title`, `startsAt`, `endsAt`, optional `notes`, optional `guests` (an array of Gnesi addresses), optional `clientRequestId`.

Times are ISO 8601 instants. The same `clientRequestId` from this caller returns the appointment already saved.

A guest whose door would refuse a new contact is left off. The organizer's appointment is still saved. An email-only address is not a guest.

## Response

`appointment` is the organizer's row, status `confirmed`. `guestRefusals` is the guest addresses that were not added.

```sample
curl -X POST "https://api.gnesi.io/v1/appointments" \
  -H "Authorization: Bearer $GNESI_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{"title":"Intro","startsAt":"2026-10-20T15:00:00.000Z","endsAt":"2026-10-20T15:30:00.000Z","notes":"Bring the brief.","guests":["mina@gnesi.io","bea@gnesi.io"],"clientRequestId":"req_123"}'
```

```payload
{"title":"Intro","startsAt":"2026-10-20T15:00:00.000Z","endsAt":"2026-10-20T15:30:00.000Z","notes":"Bring the brief.","guests":["mina@gnesi.io","bea@gnesi.io"],"clientRequestId":"req_123"}
```

```result
{
  "appointment": {
    "id": "appointment_123",
    "title": "Intro",
    "startsAt": "2026-10-20T15:00:00.000Z",
    "endsAt": "2026-10-20T15:30:00.000Z",
    "notes": "Bring the brief.",
    "status": "confirmed",
    "organizer": "ada@gnesi.io",
    "guests": ["mina@gnesi.io"]
  },
  "guestRefusals": ["bea@gnesi.io"]
}
```