Public API

Fellesly has a REST API for your own scripts, automations and integrations: put dinner on the shopping list from Home Assistant, push events from a club's system into the calendar, or build a dashboard for the hallway.

• Base URL: your API address plus /v1, e.g. https://api.fellesly.no/v1 (self-hosted: your PUBLIC_URL).
• Format: JSON in, JSON out. Times are ISO 8601; family time is Europe/Oslo.
• Auth: a personal access token in Authorization: Bearer fly_….
• Spec: an OpenAPI 3.1 document at /v1/openapi.json. The reference lists every endpoint.

What a token can reach

Area	Read token	Write token
GET /v1/me (account and families)	✓	✓
Family data under /v1/families/{fid}/…	✓	✓
Creating, updating, deleting family data		✓
Assistant chats and memories, live location, calendar share links
Account, sign-in, tokens, export, deletion
Family administration (members, settings, closing)
Admin dashboard

Writes are exactly the family actions the assistant can suggest (events, lists and items, routines, meals, recipes, reminders, places, contacts, budget, the week plan and more). See the reference.

On top of the token's scope, every request goes through the same checks as the app: you must be a member of the family, your role must allow the change (a Read member cannot write even with a write token), and you see only what your visibility settings allow.

Errors

Errors are JSON with an error message, and issues for validation failures:

{ "error": "Validation failed", "issues": [{ "path": ["title"], "message": "Too small" }] }

Status	Meaning
400	Invalid body or query
401	Missing, unknown, revoked or expired token
403	The token's scope, the endpoint, or your role does not allow it
404	Not found, or not visible to you
409	Conflict, e.g. a limit was reached
423	The family is closed
429	Rate limit reached

Rate limits

Each token may make 120 requests per minute. Past that, requests get 429 until the next minute.

Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Rate windows persist across API restarts. On 429, wait for Retry-After seconds before trying again.

Pagination and retries

Public array reads return at most 50 records by default; limit accepts 1–100. They use stable identifier ordering (calendar occurrences also include their start time). Pass q for case-insensitive matching of names, titles, text, display names or captions. When X-Next-Cursor is present, repeat the same resource and filters with that value in cursor. Continue until the header is absent. Cursors are not snapshots: concurrent inserts before the cursor appear on the next complete refresh.

Array pages are limited to 48 KB, so a page can contain fewer than limit records. A single oversized record returns 413. Object responses are limited to 1 MB; narrow date ranges when reading large calendar or week aggregates. These limits apply to personal access tokens; app sessions keep their existing response shapes.

For POST writes, send an optional Idempotency-Key with 8–128 letters, digits, underscores or hyphens. The server durably reserves that key per token for 24 hours before attempting the write. Reusing it returns 409 without repeating the write. This includes validation failures and interrupted attempts: use GET to reconcile the result before submitting a corrected request with a new key. The response body is not retained. At most 1,000 keys per token are retained in the 24-hour window. Do not automatically retry POSTs without a key.

List-item creation also accepts a UUID clientId and returns the existing item when retried by the same author in the same list. Item PATCH and DELETE accept expectedVersion; a concurrent edit returns 409 for review.

OpenAPI

curl https://api.fellesly.no/v1/openapi.json -o fellesly.openapi.json

The spec needs no token. Load it into Postman, Insomnia, Bruno or a code generator such as openapi-typescript.

Calendar reads accept optional ISO 8601 from and to bounds. The week board requires both bounds as Oslo dates (YYYY-MM-DD). Daily and weekly briefings accept an optional date; the weekly endpoint is /v1/families/{fid}/briefing/week. These query parameters are included in the generated contract.

Token permissions are documented in x-token-scope. The HTTP bearer security requirement has an empty scope array; OAuth scopes do not apply to these tokens. Request and success response types are checked with openapi-typescript and the TypeScript compiler in the API test suite. Read and write responses use shared schemas, including arrays, briefing and budget aggregates, nullable custody plans, and bodyless deletions. Authenticated API tests check returned data against those contracts. Generated TypeScript types do not perform runtime validation; integrations accepting untrusted data should also validate it against the OpenAPI schemas.

Versioning

Everything is under /v1. Within v1, fields and endpoints may be added; removals and breaking changes go into a new version.