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