# famapp HTTP API (v1)

REST JSON API under `/api/v1/`. Full OpenAPI spec is planned in task 87.3.

## Authentication

Every endpoint accepts **either**:

- Auth.js session cookie (browser login), or
- `Authorization: Bearer <household-api-token>` header

Unauthorized requests return `401` with `{ "error": "Unauthorized" }`.

Generate bearer tokens in **Settings → API tokens**.

## Endpoints (87.2)

### Calendars

| Method | Path                    | Description                                              |
| ------ | ----------------------- | -------------------------------------------------------- |
| GET    | `/api/v1/calendars`     | List visible calendars                                   |
| POST   | `/api/v1/calendars`     | Create calendar (`name`, optional `color`, `visibility`) |
| GET    | `/api/v1/calendars/:id` | Get calendar                                             |
| PATCH  | `/api/v1/calendars/:id` | Update `name`, `visibility`, `color`                     |
| DELETE | `/api/v1/calendars/:id` | Delete calendar                                          |

### Events

| Method | Path                                    | Description                                                           |
| ------ | --------------------------------------- | --------------------------------------------------------------------- |
| GET    | `/api/v1/events?from=&to=&calendarIds=` | List events in range (`calendarIds` = `all` or comma-separated UUIDs) |
| POST   | `/api/v1/events`                        | Create event                                                          |
| GET    | `/api/v1/events/:id`                    | Get event                                                             |
| PATCH  | `/api/v1/events/:id`                    | Update event                                                          |
| DELETE | `/api/v1/events/:id`                    | Delete event                                                          |

### Lists

| Method | Path                              | Description                                                   |
| ------ | --------------------------------- | ------------------------------------------------------------- |
| GET    | `/api/v1/lists?type=`             | List lists (optional `type` filter, e.g. `shopping`, `tasks`) |
| POST   | `/api/v1/lists`                   | Create list (`type`, `name`)                                  |
| GET    | `/api/v1/lists/:id`               | Get list with items                                           |
| PATCH  | `/api/v1/lists/:id`               | Update `name` or `archived`                                   |
| DELETE | `/api/v1/lists/:id`               | Archive list                                                  |
| GET    | `/api/v1/lists/:id/items`         | List items                                                    |
| POST   | `/api/v1/lists/:id/items`         | Add item                                                      |
| PATCH  | `/api/v1/lists/:id/items/:itemId` | Update or toggle item (`done`)                                |
| DELETE | `/api/v1/lists/:id/items/:itemId` | Delete item                                                   |

### Notes

| Method | Path                | Description |
| ------ | ------------------- | ----------- |
| GET    | `/api/v1/notes`     | List notes  |
| POST   | `/api/v1/notes`     | Create note |
| GET    | `/api/v1/notes/:id` | Get note    |
| PATCH  | `/api/v1/notes/:id` | Update note |
| DELETE | `/api/v1/notes/:id` | Delete note |

## Bearer token visibility

Bearer tokens see **household-visible calendars only** (private calendars are hidden). Mutations on calendars require ownership (session) or household visibility (bearer). Activity log records `actorId: null` for bearer mutations.

## Planned (87.3)

- Garden, bangs routes
- OpenAPI specification