Rigel's routines

agent.routine.list

GET/api/v1/households/{household_id}/queries/agent.routine.list

Query
Rigel runs it

Lists the routines Rigel runs on its own: what each does, when it repeats, who it is for, whether it is paused, and when it last ran and runs next. Oldest first. Give routine_id for just one. Check it before setting up a routine, so you update an existing one instead of adding a second.

Parameters#

Rigel's routines: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`routine_id`querystringoptional	Only this routine.

Response#

200 The answer.

Rigel's routines: response fields
Field	Description
`routines`array of objectsrequired
`routines[].id`stringrequired	A agent routine ID, such as rtn_01JC0000000000000000000000.
`routines[].title`stringrequired	What it does, in plain words.
`routines[].task`stringrequired	The instructions Rigel follows each time.
`routines[].app`one of: meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenance, null or nullrequired	The app whose guide it reads, or null.
`routines[].for_person_id`stringrequired	Whose authority it runs with and who it is for.
`routines[].for_person_name`stringrequired	That person's name.
`routines[].for_user_id`string or nullrequired	The account that person signs in with, or null if they have none.
`routines[].repeat`one of 4 shapesrequired	How often it runs: daily at a time, weekly on some days, monthly on a day (1–28), or once on a date. Example: { "kind": "weekly", "days": ["wed"], "time": "09:00" }.
Shape 1
`routines[].repeat.kind`one of: dailyrequired	No description.
`routines[].repeat.time`stringrequired	The time of day in the household's time zone, 24-hour "HH:MM", such as "09:00". pattern ^([01]\d\|2[0-3]):[0-5]\d$
Shape 2, with days
`routines[].repeat.kind`one of: weeklyrequired	No description.
`routines[].repeat.days`array, each one of: mon, tue, wed, thu, fri, sat, sunrequired	The days of the week: "mon", "tue", "wed", "thu", "fri", "sat", "sun". 1 to 7 items
`routines[].repeat.time`stringrequired	The time of day in the household's time zone, 24-hour "HH:MM", such as "09:00". pattern ^([01]\d\|2[0-3]):[0-5]\d$
Shape 3, with day
`routines[].repeat.kind`one of: monthlyrequired	No description.
`routines[].repeat.day`integerrequired	The day of the month, 1 to 28, so every month has it. 1 to 28
`routines[].repeat.time`stringrequired	The time of day in the household's time zone, 24-hour "HH:MM", such as "09:00". pattern ^([01]\d\|2[0-3]):[0-5]\d$
Shape 4, with date
`routines[].repeat.kind`one of: oncerequired	No description.
`routines[].repeat.date`stringrequired	A calendar date in the household's time zone, YYYY-MM-DD. pattern ^\d{4}-\d{2}-\d{2}$
`routines[].repeat.time`stringrequired	The time of day in the household's time zone, 24-hour "HH:MM", such as "09:00". pattern ^([01]\d\|2[0-3]):[0-5]\d$
`routines[].paused`booleanrequired	No description.
`routines[].next_run_at`integer or nullrequired	When it runs next, UTC milliseconds; null if paused or finished.
`routines[].last_run_at`integer or nullrequired	When it last ran, UTC milliseconds, or null.
`routines[].created_at`integerrequired	No description.

Errors#

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

Rigel's routines: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

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

List Rigel's routines

Oldest first, with when each last ran and runs next.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.routine.list' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.routine.list", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.routine.list HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTCCW6XNKYGM1FN77ZYE

{
  "routines": [
    {
      "id": "rtn_01M6V9CTC5VNP0HS02R6Q1BQHB",
      "title": "Nudge us to plan meals",
      "task": "On Sunday evening, if next week has fewer than five dinners planned, post a dashboard card that asks whether to plan the rest.",
      "app": "meals",
      "for_person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
      "for_person_name": "Ada Okafor",
      "for_user_id": "usr_01M6V9CS5XV66GR856KS52MTTZ",
      "repeat": {
        "kind": "weekly",
        "days": [
          "sun"
        ],
        "time": "17:30"
      },
      "paused": false,
      "next_run_at": 1794180600000,
      "last_run_at": null,
      "created_at": 1794064673157
    },
    {
      "id": "rtn_01M6V9CTC7NW649VMCSKRPFYS2",
      "title": "Check the filter supply",
      "task": "On the first of the month, check that the pantry has a furnace filter. If it doesn't, add a pack to the shopping list and post a card that says so.",
      "app": "shopping",
      "for_person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
      "for_person_name": "Ada Okafor",
      "for_user_id": "usr_01M6V9CS5XV66GR856KS52MTTZ",
      "repeat": {
        "kind": "monthly",
        "day": 1,
        "time": "09:00"
      },
      "paused": true,
      "next_run_at": null,
      "last_run_at": null,
      "created_at": 1794064673159
    }
  ]
}

Look at one routine

A paused routine has no next run.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.routine.list?routine_id=rtn_01M6V9CTC7NW649VMCSKRPFYS2' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.routine.list?routine_id=rtn_01M6V9CTC7NW649VMCSKRPFYS2", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.routine.list?routine_id=rtn_01M6V9CTC7NW649VMCSKRPFYS2 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTCE8KSD4JRTEAZCCG0P

{
  "routines": [
    {
      "id": "rtn_01M6V9CTC7NW649VMCSKRPFYS2",
      "title": "Check the filter supply",
      "task": "On the first of the month, check that the pantry has a furnace filter. If it doesn't, add a pack to the shopping list and post a card that says so.",
      "app": "shopping",
      "for_person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
      "for_person_name": "Ada Okafor",
      "for_user_id": "usr_01M6V9CS5XV66GR856KS52MTTZ",
      "repeat": {
        "kind": "monthly",
        "day": 1,
        "time": "09:00"
      },
      "paused": true,
      "next_run_at": null,
      "last_run_at": null,
      "created_at": 1794064673159
    }
  ]
}

For Rigel#

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