IDs and formats

A record's ID is a short lowercase prefix, an underscore and a 26-character ULID. The prefix says what kind of record the ID names.

rcp_01JC9C1H8W3ZT6QXN5KDV2RMYA

The 26 characters are digits and capital letters, leaving out I, L, O and U. Treat the whole string as opaque: store it as text, compare it for equality, and don't read meaning out of it or sort a list by it except as a tiebreaker. Lists come back in the order each query documents.

The IDs of rows a command creates are derived from the command's own ID, which is the Idempotency-Key you send. Sending the same command with the same key again returns the same rows rather than making new ones. The commands guide covers retries.

A few IDs are fixed so a client can use them before anything exists. The household's main chat is cnv_00000000000000000000000000.

Having an ID grants no access. Every household route checks that you belong to the household. A household you aren't in answers 404 not_found as if it didn't exist, so none of its records can be reached either. An ID with the wrong prefix for its field is a 400 validation_failed that names the field, such as "must be a recipe ID starting with rcp_".

These are all the prefixes today. A field that takes a recipe ID takes an rcp_ ID, and so on. Some kinds of record are kept only on the server and never sent to clients. A few IDs are not records at all: cmd_ is the Idempotency-Key of a command, cli_ names a device that syncs, and req_ is the X-Request-Id header on every response.

A field that can point at any record, such as record_id on notifications.notification.send, accepts an ID with any prefix in this table.

Time comes in four forms.

• An instant is ISO 8601 in UTC, with milliseconds: 2026-11-09T16:00:00.000Z. Most command and query responses write instants like this, and the fields are named …_at. The calendar's queries write an event's start and end with the household's offset instead, such as 2026-11-09T10:00:00-06:00. The rows of a pull, the routes under /agent, the socket's messages, the routines and triggers of the agent area, the Today query dashboard.day.get and the Drive browser use integer UTC milliseconds instead, such as 1794240000000. The field's description says which.
• An instant you send is ISO 8601 with a zone: 2026-11-09T10:00:00-06:00 or the same moment as 2026-11-09T16:00:00Z. A few fields, such as a calendar event's start and end, also take wall-clock time without a zone, 2026-11-09T10:00, and read it in the event's own time zone. The field's description says when that is allowed.
• A calendar date is YYYY-MM-DD with no time zone and no conversion: 2026-11-11. A best-by date, a birthday and the day of a meal are dates. Don't send midnight as a stand-in for one.
• A repeating local time, such as Wednesdays at 9 am, is kept as a local time and day and uses the household's time zone, an IANA name such as America/Chicago that you give when you create the household.

A pull returns stored rows, which is why their times are milliseconds and their booleans are 1 and 0.

A date that is only partly known carries a precision field rather than pretending. A person's birth date has birth_date_precision, one of day, month or year. With month the day is 01 and means nothing.

An amount is a number and a unit in two separate fields, and the unit is never written inside a string. The number is more than 0 and at most 1,000,000. The unit is an ID from one fixed list. A unit left out or sent as null means a plain count of the things themselves, like 3 eggs.

{ "name": "garlic", "quantity": 2, "quantity_max": 3, "unit": "clove" }

The field names follow the app. A recipe ingredient has quantity, quantity_max for the top of a range, and unit. A shopping list item has quantity and unit. An inventory item has quantity and quantity_unit, plus size_value and size_unit for the size of one package.

Money is an integer count of minor units with a currency code, never a decimal: 499 is $4.99 in USD. Shopping trips record receipt prices and totals as price_minor and total_minor with a currency, and Maintenance records costs, quotes and invoices the same way. The currency is required whenever an amount is given.

JSON fields, query parameters and path parameters are all snake_case. A single record comes back as itself, with no wrapper around it. Booleans in responses are true and false. Enums are strings, and the field's description names every value. Text that people write is stored as written, without trimming or reformatting.

Null and omitted mean different things. On a command that changes a record, a field you leave out is left alone, and a field you send as null is cleared, where the field allows null. This clears a birth date:

{
  "person_id": "per_01JC8Q5X0RT4M8ZVB2HNQ6EK1Y",
  "birth_date": null,
  "birth_date_precision": null
}

Responses spell "nothing" as null, and each field in the reference says whether it can be.

Each real-world thing has one record, and everything else points at it by ID instead of copying its name. A meal points at its dishes, a recipe ingredient at a product, an inventory item at its place and at the person it is kept for. The fields are named …_id, and the ID is the whole link. To show a person what a record says, read the record, not a copy.

Every kind of record also has an address in the web app, which can be worked out from the ID alone. A record with no screen of its own opens the screen that shows it. A client can link to any record in this table with https://rigel.house and the path, where {id} is the record's whole ID, prefix included. The page opens for a signed-in member of the household.

Prefixes not in this table have no address yet. A notification sent with notifications.notification.send and a record_id opens that record when someone taps it.