# Hour

Hour is a scheduling product with public profile pages for requesting meeting times.

## Agent Entry Points

- Public profile page: `/{username}`
- Profile API: `/api/v1/profiles/{username}`
- Availability API: `/api/v1/profiles/{username}/availability`
- Booking request API: `/api/v1/profiles/{username}/bookings`
- API credentials dashboard: `/dashboard/api`
- Connected calendars API: `/api/v1/me/calendars`
- Unified calendar events API: `/api/v1/me/events`
- Agent manifest: `/.well-known/agent.json`
- OpenAPI description: `/openapi.json`

## Booking Flow

1. Fetch `/api/v1/profiles/{username}/availability`.
2. Choose a slot from the `slots` array.
3. POST to `/api/v1/profiles/{username}/bookings` with:

```json
{
  "slot_id": "slot id from availability",
  "booker_email": "person@example.com",
  "notes": "Optional context for the host"
}
```

The API creates a pending booking request. The host still reviews and accepts or rejects the request before it is confirmed.

Browser agents may also open `booking_url`, click `[data-agent-action="book-slot"]`, and complete the visible request flow. Browser booking currently requires a signed-in user session.

## Slot Semantics

Slot timestamps are ISO 8601 instants. The public page displays times in the visitor timezone.

## Host Calendar API

Authenticated agents can manage the signed-in host's connected calendars through one provider-neutral API.

Hosts create or rotate one active Hour API credential pair in `/dashboard/api`. Agents can authenticate with `X-Hour-API-Key` and `X-Hour-API-Secret` headers, or with a Supabase bearer token/session.

- `GET /api/v1/me/calendars` lists connected calendar accounts.
- `GET /api/v1/me/events?start={isoStart}&end={isoEnd}` lists events across connected providers.
- `POST /api/v1/me/events` creates an event on the selected connected calendar.

```json
{
  "calendar_account_id": "optional connected calendar id",
  "title": "Customer call",
  "description": "Optional notes",
  "start": "2026-05-20T02:00:00.000Z",
  "end": "2026-05-20T02:30:00.000Z",
  "time_zone": "Asia/Singapore",
  "attendees": [{ "email": "person@example.com" }],
  "conference": true
}
```

The API hides provider-specific OAuth details. Google is currently supported; future providers should reuse the same request and response shapes.