97 lines
5.6 KiB
Markdown
97 lines
5.6 KiB
Markdown
# famapp HTTP API (v1)
|
|
|
|
REST JSON API under `/api/v1/`. Full specification: [`openapi.yaml`](openapi.yaml).
|
|
|
|
## Authentication
|
|
|
|
Every endpoint accepts **either**:
|
|
|
|
- Auth.js session cookie (browser login), or
|
|
- `Authorization: Bearer <household-api-token>` header (recommended for external clients)
|
|
|
|
Unauthorized requests return `401` with `{ "error": "Unauthorized" }`.
|
|
|
|
Generate bearer tokens in **Settings → API tokens**. Example:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer YOUR_TOKEN" https://fam.ginnoir.com/api/v1/calendars
|
|
```
|
|
|
|
## OpenAPI
|
|
|
|
See [`openapi.yaml`](openapi.yaml) for paths, request/response schemas, and the `bearerAuth` security scheme. Import into Swagger UI, Postman, or your HTTP client of choice.
|
|
|
|
## Endpoints
|
|
|
|
### 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 |
|
|
|
|
### Garden
|
|
|
|
| Method | Path | Description |
|
|
| ------ | ------------------------------- | -------------------------------------- |
|
|
| GET | `/api/v1/garden/containers` | List containers |
|
|
| POST | `/api/v1/garden/containers` | Create container |
|
|
| GET | `/api/v1/garden/containers/:id` | Get container with plants |
|
|
| PATCH | `/api/v1/garden/containers/:id` | Update container |
|
|
| DELETE | `/api/v1/garden/containers/:id` | Delete container |
|
|
| GET | `/api/v1/garden/plants` | List plants (optional `?containerId=`) |
|
|
| POST | `/api/v1/garden/plants` | Create plant |
|
|
| GET | `/api/v1/garden/plants/:id` | Get plant detail |
|
|
| PATCH | `/api/v1/garden/plants/:id` | Update plant |
|
|
| DELETE | `/api/v1/garden/plants/:id` | Delete plant |
|
|
|
|
### Bangs
|
|
|
|
| Method | Path | Description |
|
|
| ------ | ------------------- | ------------------------------------------------ |
|
|
| GET | `/api/v1/bangs` | Stats: `total` + `recent` (optional `?limit=10`) |
|
|
| POST | `/api/v1/bangs` | Record bang (optional `occurredOn` YYYY-MM-DD) |
|
|
| PATCH | `/api/v1/bangs/:id` | Update `occurredOn` |
|
|
| DELETE | `/api/v1/bangs/:id` | Delete bang |
|
|
|
|
## 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.
|