Add sample data

sample_data.post

POST/api/v1/households/{household_id}/sample-data

Route

Fills the household with a made-up family's records (people and notes, a pantry, recipes, a meal plan, a calendar, a family chat and more) through the same commands people use, so you can see Rigel in use. Nothing already in the household is changed, and nothing reaches outside it: no email is sent and no work runs afterward. Every record it makes is marked, and household.sample.clear takes them all out again. Admins only. Fails with sample_exists while the household still has sample data.

Parameters#

Add sample data: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.

Response#

201 What was added.

Add sample data: response fields
Field	Description
`records`integerrequired	How many records were added, all marked as sample data.
`apps`array of objectsrequired	The records added, by app, in the order they were added.
`apps[].app`stringrequired	The app, or "family" for people and notes.
`apps[].records`integerrequired	How many of its records were added.
`failed`object or nullrequired	Null when everything was added. Otherwise the app that stopped partway; what was added before it is still marked and can be cleared.
`failed.app`stringrequired	The app whose sample data stopped partway.
`failed.code`stringrequired	The error code of the command that was refused.

Errors#

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

Add sample data: errors
Status	Code	When
`401`	`unauthenticated`	The request has no valid session.
`403`	Read error.code	Described above.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	Read error.code	Described above.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Fill a household with a made-up family

Every record it adds is marked as sample data, so one command can take it all out again.

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CTF2YQWZD4QYP8NGFJXF/sample-data' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CTF2YQWZD4QYP8NGFJXF/sample-data", {
  method: "POST",
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01M6V9CTF2YQWZD4QYP8NGFJXF/sample-data HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 201

HTTP/1.1 201 Created
Content-Type: application/json
X-Request-Id: req_01M6V9CTFBDMHWK82Q29PCMKDE

{
  "records": 1258,
  "apps": [
    {
      "app": "family",
      "records": 19
    },
    {
      "app": "calendar",
      "records": 73
    },
    {
      "app": "tasks",
      "records": 117
    },
    {
      "app": "inventory",
      "records": 136
    },
    {
      "app": "maintenance",
      "records": 122
    },
    {
      "app": "recipes",
      "records": 255
    },
    {
      "app": "meals",
      "records": 217
    },
    {
      "app": "shopping",
      "records": 83
    },
    {
      "app": "chat",
      "records": 147
    },
    {
      "app": "email",
      "records": 66
    },
    {
      "app": "documents",
      "records": 20
    },
    {
      "app": "dashboard",
      "records": 3
    }
  ],
  "failed": null
}

Sample data that's already there

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CTF2YQWZD4QYP8NGFJXF/sample-data' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CTF2YQWZD4QYP8NGFJXF/sample-data", {
  method: "POST",
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01M6V9CTF2YQWZD4QYP8NGFJXF/sample-data HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 409

HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01M6V9CVD0VWS2VMVCBSB12KR0

{
  "error": {
    "code": "sample_exists",
    "message": "This household already has sample data. Nothing was added.",
    "details": {
      "records": 1258
    },
    "recovery": "Clear the sample data first with household.sample.clear, then add it again.",
    "request_id": "req_01M6V9CVD0VWS2VMVCBSB12KR0"
  }
}