Skip to content
Rigel docs
Open Rigel

Add someone to the immediate family

family.person.add

POST/api/v1/households/{household_id}/commands/family.person.add

  • Command
  • Rigel runs it
  • Applies offline

Adds a person to the household's immediate family, last on the page. Only immediate family are people; note anything about others on the household instead.

Parameters#

Add someone to the immediate family: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

Idempotency-Keyheaderstringoptional

The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Add someone to the immediate family: request body fields
FieldDescription
namestringrequired

What the family calls them, as written, 1–80 characters.

at most 80 characters
birth_datestring (date) or nulloptional

A calendar date, YYYY-MM-DD.

birth_date_precisionone of: day, month, year, null or nulloptional

How much of birth_date is known: day (the full date), month (the day is 01 and means nothing), or year (the month and day are 01-01).

Response#

200 The command was applied.

Add someone to the immediate family: response fields
FieldDescription
resultobjectrequired

What the command returned, such as the IDs it created.

result.person_idstringrequired

The new person.

versionintegerrequired

The household version after the command.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Add someone to the immediate family: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404not_foundThe household doesn't exist, or you aren't a member of it.
409idempotency_key_reusedThe Idempotency-Key was already used for a different command.

Examples#

These are real. Each scenario is one of the command's test cases, run on a household when this site was built, and the response is what the API returned.

The first person goes first, with an ID derived from the command

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/family.person.add' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "name": "Nia"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/family.person.add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    name: "Nia",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/family.person.add HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "name": "Nia"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0N24QBC0MH6021006

{
  "result": {
    "person_id": "per_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A new person goes after everyone else, with a birth date

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/family.person.add' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "name": "Theo",
  "birth_date": "2025-01-01",
  "birth_date_precision": "month"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/family.person.add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    name: "Theo",
    birth_date: "2025-01-01",
    birth_date_precision: "month",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/family.person.add HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "name": "Theo",
  "birth_date": "2025-01-01",
  "birth_date_precision": "month"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0EG4E6CYJNJWDN8T3

{
  "result": {
    "person_id": "per_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

Add a person

A person doesn't need an account. Rigel can plan meals and keep notes about people who never sign in.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CS7466CD9P7BFE4D58WR' \
  -d '{
  "name": "Ben Okafor"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CS7466CD9P7BFE4D58WR",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    name: "Ben Okafor",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CS7466CD9P7BFE4D58WR

{
  "name": "Ben Okafor"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CS77NTJGD5XAJC8F0FX4

{
  "result": {
    "person_id": "per_01M6V9CS744BQQH188FS6CXY9W"
  },
  "version": 2
}

Add a child

A birth date gives the person an age, such as 8 years old.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CS79VDWTD6NC1ASABTKD' \
  -d '{
  "name": "Nia",
  "birth_date": "2018-03-14",
  "birth_date_precision": "day"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CS79VDWTD6NC1ASABTKD",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    name: "Nia",
    birth_date: "2018-03-14",
    birth_date_precision: "day",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CS79VDWTD6NC1ASABTKD

{
  "name": "Nia",
  "birth_date": "2018-03-14",
  "birth_date_precision": "day"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CS7ACET9RF5QB222T7G8

{
  "result": {
    "person_id": "per_01M6V9CS79TMYHDAM7FTA9ZK3Z"
  },
  "version": 3
}

Add a child by birth month

When only the month is known, say so with birth_date_precision.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CS7C4V4FHNX9GB6BNQ9F' \
  -d '{
  "name": "Theo",
  "birth_date": "2021-08-01",
  "birth_date_precision": "month"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CS7C4V4FHNX9GB6BNQ9F",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    name: "Theo",
    birth_date: "2021-08-01",
    birth_date_precision: "month",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CS7C4V4FHNX9GB6BNQ9F

{
  "name": "Theo",
  "birth_date": "2021-08-01",
  "birth_date_precision": "month"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CS7C6JMG2ESV2E27F4PH

{
  "result": {
    "person_id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6"
  },
  "version": 4
}

A request with invalid fields

Every field problem is listed in details.fields, so one retry can fix them all.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CTCYYXTV2X3874M7ZMAW' \
  -d '{
  "name": "",
  "birth_date": "2018-03-14"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CTCYYXTV2X3874M7ZMAW",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    name: "",
    birth_date: "2018-03-14",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/family.person.add HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CTCYYXTV2X3874M7ZMAW

{
  "name": "",
  "birth_date": "2018-03-14"
}
Response, 400
HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-Id: req_01M6V9CTCY8RHCWW5SB9P7VBQS

{
  "error": {
    "code": "validation_failed",
    "message": "The request has invalid fields. No changes were applied.",
    "details": {
      "fields": [
        {
          "field": "name",
          "problem": "must not be blank"
        },
        {
          "field": "birth_date_precision",
          "problem": "birth_date and birth_date_precision must be given together"
        }
      ]
    },
    "recovery": "Correct each field listed in details.fields, then send the request again.",
    "request_id": "req_01M6V9CTCY8RHCWW5SB9P7VBQS"
  }
}

For Rigel#

Rigel's tool for this command is family_person_add. Rigel runs this on its own, then says what it did. The agent guide has the rest.

Rigel is in early access, and sign-up is by invitation. Open Rigel