How the API fits together

A household is one family's workspace in Rigel: its people, meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, home maintenance and files. Each household's data is kept apart from every other household's. You reach one by its ID, which starts with hh_ and appears in the path of every request about it.

A person who signs in has an account, and one account can belong to several households. Everything else, including the people in the family, belongs to a single household. Households and people covers the difference.

Every path is under https://rigel.house/api/v1. Routes come in two kinds. Directory routes are about accounts and households themselves: who you are, which households you belong to, creating one. Household routes act inside one household, and every one of them starts with /households/{household_id}.

Directory routes, under /api/v1
  /health                                Is the API up (public)
  /openapi.json and /docs                The OpenAPI document and its viewer (public)
  /socket-schema.json                    JSON Schema of the socket's messages (public)
  /auth/...                              Sign in and out
  /me                                    Who you are, and your households
  /push/config                           The key for a browser's web push subscription
  /me/push-subscription                  Save or remove this browser's push subscription
  /households                            Create a household
  /integrations/google/callback          Where Google sends the browser back after connecting an account

Household routes, under /api/v1/households/{household_id}
  (nothing more)                         One household's settings and your role
  /commands/{name}                       Change something (POST)
  /queries/{name}                        Read something (GET)
  /pull                                  Rows changed since a version (sync)
  /sync/push                             A device's queued commands (sync)
  /sample-data                           Fill the household with a made-up family (POST)
  /files                                 Upload and read files
  /email/...                             Rigel's addresses, custom domains and an email's HTML
  /documents/google/files                Browse a connected Google Drive
  /integrations/{service}/connect        Connect an outside account (browser)
  /agent/conversations                   Your conversations with Rigel
  /socket                                Live updates (WebSocket)

Almost everything else is a command or a query. The routes above are written by hand because they carry bytes, redirect a browser, claim something across households or aren't request and response at all. Each has a guide: households, sample data and notifications, sync, files, email, outside accounts, Rigel and the socket.

Start with GET /api/v1/me. It lists your households and their IDs, which is what every household route needs.

Every change to a household is a command, a named action with a JSON input. Every read of shared household data is a query, a named question with flat parameters. Both are named <app>.<record>.<verb>, such as family.note.record and inventory.item.adjust.

POST /api/v1/households/{household_id}/commands/family.note.record
GET  /api/v1/households/{household_id}/queries/family.person.list

A command answers with { "result": …, "version": 42 }: what it created or returned, and the household's version after it ran. A query answers with the data itself. Nothing else writes household data. The web app, Rigel and your scripts all go through the same commands, so anything the app can change, the API can change. The one exception is file bytes, which are uploaded to a file route (see the files guide).

The Rigel apps keep a copy of the household on the device. They run a command against that copy first, so the screen changes at once and keeps working offline, and send it to the household later with POST /api/v1/households/{household_id}/sync/push. They catch up with GET /api/v1/households/{household_id}/pull, which returns every row changed since a household version. The version is a number that goes up by one with each applied command, so it tells a device what it is missing.

A script that reads or changes a few things doesn't need any of this. Call commands and queries over HTTP. If you are building a client that keeps its own copy, read the sync guide.

The household socket (GET /api/v1/households/{household_id}/socket, a WebSocket upgrade) tells open apps when the household changed, so they pull at once, and carries presence: who is online and which page they are on. It also carries conversations with Rigel and the text of documents that people edit together. See the household socket guide.

Rigel works on every screen of the app. It reaches a household only through the same commands and queries you can call. What it changes is recorded as made by Rigel, for the person who asked.

Rigel also works on its own: on a schedule, after something happens, when an email arrives and when someone mentions it in the family chat. Each command says whether Rigel may run it on its own, must ask first, or never runs it. That policy applies to Rigel, not to your requests. See the commands guide and the agent guide.

The guides explain the ideas a client needs: Quickstart, Authentication, Commands, Queries and lists and Errors and retries, then the parts of Rigel that behave in their own way, and the formats behind it all. They are written by hand.

The reference lists every operation, grouped by area: an app such as Inventory, or a foundation area such as Account. Each operation's page is generated from the code at every deploy. Its parameters, response fields, errors and Rigel policy are current, and its examples are recorded from the real API.

The same information is available to tools. The OpenAPI 3.1 document is at https://rigel.house/api/v1/openapi.json, and the API serves an interactive view of it at https://rigel.house/api/v1/docs. Neither needs a session.