famapp/docs/api/README.md

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.