ginnoir
a09747c314
Journal dashboard widgets and quick-add; rich-text quick-add dialogs. Dashboard draft sync for live edit previews; assistant bubble + API tools. Journal UX: stress slider, mood grid, query cap fix.
famapp HTTP API (v1)
REST JSON API under /api/v1/. Full specification: 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:
curl -H "Authorization: Bearer YOUR_TOKEN" https://fam.ginnoir.com/api/v1/calendars
OpenAPI
See 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.