Rigel's triggers

agent.trigger.list

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

Query
Rigel runs it

Lists the triggers that make Rigel act after something happens: what each does, the commands that set it off, when it acts, who it is for, whether it is paused, and when it last ran. Oldest first. Give trigger_id for just one. Check it before setting up a trigger, so you update an existing one instead of adding a second.

Parameters#

Rigel's triggers: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`trigger_id`querystringoptional	Only this trigger.

Response#

200 The answer.

Rigel's triggers: response fields
Field	Description
`triggers`array of objectsrequired
`triggers[].id`stringrequired	A agent trigger ID, such as trg_01JC0000000000000000000000.
`triggers[].title`stringrequired	What it does, in plain words.
`triggers[].task`stringrequired	The instructions Rigel follows each time.
`triggers[].app`one of: meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenance, null or nullrequired	The app whose guide it reads, or null.
`triggers[].for_person_id`stringrequired	Whose authority it runs with and who it is for.
`triggers[].for_person_name`stringrequired	That person's name.
`triggers[].for_user_id`string or nullrequired	The account that person signs in with, or null if they have none.
`triggers[].commands`array of stringsrequired	The commands that set it off, by tool name.
`triggers[].when`one of 3 shapesrequired	When Rigel acts after the event: "soon" (about a minute after, so a burst of changes is one run), "after" some minutes, or "at" a time of day (the next time the household's clock shows it, at least a minute after the event). Example: { "kind": "at", "time": "19:00" }.
Shape 1
`triggers[].when.kind`one of: soonrequired	No description.
Shape 2, with minutes
`triggers[].when.kind`one of: afterrequired	No description.
`triggers[].when.minutes`integerrequired	How long after the event, 1 to 1,440 minutes (one day). 1 to 1,440
Shape 3, with time
`triggers[].when.kind`one of: atrequired	No description.
`triggers[].when.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$
`triggers[].paused`booleanrequired	No description.
`triggers[].last_run_at`integer or nullrequired	When it last ran, UTC milliseconds, or null.
`triggers[].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 triggers: 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 triggers

Oldest first, with the commands that set each off.

Request, curl

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

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.trigger.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_01M6V9CTCP6GYBDXQ95NPW9BSF

{
  "triggers": [
    {
      "id": "trg_01M6V9CTCG6HY7NK67ENWMSS1Z",
      "title": "Ask how a new recipe went",
      "task": "When a recipe is cooked for the first time, ask that evening how it went and whether to keep it in the rotation.",
      "app": "recipes",
      "for_person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
      "for_person_name": "Ada Okafor",
      "for_user_id": "usr_01M6V9CS5XV66GR856KS52MTTZ",
      "commands": [
        "recipes.cook.log"
      ],
      "when": {
        "kind": "at",
        "time": "19:30"
      },
      "paused": false,
      "last_run_at": null,
      "created_at": 1794064673169
    },
    {
      "id": "trg_01M6V9CTCJM5QBJAYNNWJSW67W",
      "title": "Restock the furnace filter",
      "task": "When the furnace filter task is checked off, look at the pantry. If there is no spare filter, add a pack to the shopping list.",
      "app": "maintenance",
      "for_person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
      "for_person_name": "Ada Okafor",
      "for_user_id": "usr_01M6V9CS5XV66GR856KS52MTTZ",
      "commands": [
        "maintenance.task.complete"
      ],
      "when": {
        "kind": "soon"
      },
      "paused": true,
      "last_run_at": null,
      "created_at": 1794064673170
    }
  ]
}

Look at one trigger

Request, curl

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

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/agent.trigger.list?trigger_id=trg_01M6V9CTCJM5QBJAYNNWJSW67W 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_01M6V9CTCRJY79D4KEG10EQW7H

{
  "triggers": [
    {
      "id": "trg_01M6V9CTCJM5QBJAYNNWJSW67W",
      "title": "Restock the furnace filter",
      "task": "When the furnace filter task is checked off, look at the pantry. If there is no spare filter, add a pack to the shopping list.",
      "app": "maintenance",
      "for_person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
      "for_person_name": "Ada Okafor",
      "for_user_id": "usr_01M6V9CS5XV66GR856KS52MTTZ",
      "commands": [
        "maintenance.task.complete"
      ],
      "when": {
        "kind": "soon"
      },
      "paused": true,
      "last_run_at": null,
      "created_at": 1794064673170
    }
  ]
}

For Rigel#

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