Skip to content
Rigel docs
Open Rigel

Change a trigger

agent.trigger.update

POST/api/v1/households/{household_id}/commands/agent.trigger.update

  • Command
  • Rigel runs it
  • Applies offline

Changes only the fields given: the title, the task, the app, who it is for, the commands it watches, or when it acts. A run already waiting keeps its time. Fails with trigger_not_found, person_not_found, or unknown_command. Returns the trigger's ID.

Parameters#

Change a trigger: 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.

Change a trigger: request body fields
FieldDescription
trigger_idstringrequired

A agent trigger ID, such as trg_01JC0000000000000000000000.

titlestringoptional

What the routine does in plain words for the list in settings, 1–120 characters, such as "Suggest a new recipe on Wednesdays".

1 to 120 characters
taskstringoptional

The instructions Rigel follows each time, up to 4000 characters, written to be read with nobody around: what to check, when to do something, and what to leave alone.

1 to 4,000 characters
appone of: meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenance, null or nulloptional

The app whose guide Rigel reads; null for none.

for_person_idstringoptional

Whose authority it runs with and who it is for.

commandsarray of stringsoptional

The commands that set it off, 1–20, by tool name with dots, such as ["recipes.cook.log"]. Any command that is not internal; the tool names you can call are the ones to use.

1 to 20 items
whenone of 3 shapesoptional

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
when.kindone of: soonrequiredNo description.
Shape 2, with minutes
when.kindone of: afterrequiredNo description.
when.minutesintegerrequired

How long after the event, 1 to 1,440 minutes (one day).

1 to 1,440
Shape 3, with time
when.kindone of: atrequiredNo description.
when.timestringrequired

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$

Response#

200 The command was applied.

Change a trigger: response fields
FieldDescription
resultobjectrequired

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

result.trigger_idstringrequired

A agent trigger ID, such as trg_01JC0000000000000000000000.

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.

Change a trigger: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404person_not_foundA person who isn't in the household.
404trigger_not_foundA trigger that isn't there.
404not_foundThe household doesn't exist, or you aren't a member of it.
409unknown_commandA name that is not a command.
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.

Changes when it acts

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000JJJJJJJJJJJJJJJJ' \
  -d '{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "when": {
    "kind": "after",
    "minutes": 90
  }
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000JJJJJJJJJJJJJJJJ",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    trigger_id: "trg_01JC00000000000000000000T1",
    when: {
      kind: "after",
      minutes: 90,
    },
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000JJJJJJJJJJJJJJJJ

{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "when": {
    "kind": "after",
    "minutes": 90
  }
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0TSJ9N23SHQSCYR4J

{
  "result": {
    "trigger_id": "trg_01JC00000000000000000000T1"
  },
  "version": 1
}

Changes the commands it watches

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000KKKKKKKKKKKKKKKK' \
  -d '{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "commands": [
    "recipes.cook.log",
    "meals.meal.update"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000KKKKKKKKKKKKKKKK",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    trigger_id: "trg_01JC00000000000000000000T1",
    commands: [
      "recipes.cook.log",
      "meals.meal.update",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000KKKKKKKKKKKKKKKK

{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "commands": [
    "recipes.cook.log",
    "meals.meal.update"
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0MX942CAB8PF1MCMG

{
  "result": {
    "trigger_id": "trg_01JC00000000000000000000T1"
  },
  "version": 1
}

Changes only the words, who it is for and the app

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000MMMMMMMMMMMMMMMM' \
  -d '{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "title": "Ask after cooking",
  "task": "Ask after.",
  "app": null,
  "for_person_id": "per_01JC000000000000000000000B"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000MMMMMMMMMMMMMMMM",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    trigger_id: "trg_01JC00000000000000000000T1",
    title: "Ask after cooking",
    task: "Ask after.",
    app: null,
    for_person_id: "per_01JC000000000000000000000B",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000MMMMMMMMMMMMMMMM

{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "title": "Ask after cooking",
  "task": "Ask after.",
  "app": null,
  "for_person_id": "per_01JC000000000000000000000B"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0TW20X5TCZYRST3HT

{
  "result": {
    "trigger_id": "trg_01JC00000000000000000000T1"
  },
  "version": 1
}

A paused trigger stays paused

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000NNNNNNNNNNNNNNNN' \
  -d '{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "when": {
    "kind": "soon"
  }
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000NNNNNNNNNNNNNNNN",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    trigger_id: "trg_01JC00000000000000000000T1",
    when: {
      kind: "soon",
    },
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000NNNNNNNNNNNNNNNN

{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "when": {
    "kind": "soon"
  }
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0YBMZGG4RCAS0CX0E

{
  "result": {
    "trigger_id": "trg_01JC00000000000000000000T1"
  },
  "version": 1
}

Giving nothing to change changes nothing

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

{
  "trigger_id": "trg_01JC00000000000000000000T1"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0W5WBDR04F61MMAAP

{
  "result": {
    "trigger_id": "trg_01JC00000000000000000000T1"
  },
  "version": 1
}

A name that is not a command

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000QQQQQQQQQQQQQQQQ' \
  -d '{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "commands": [
    "recipes.cook.recrod"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000QQQQQQQQQQQQQQQQ",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    trigger_id: "trg_01JC00000000000000000000T1",
    commands: [
      "recipes.cook.recrod",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/agent.trigger.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000QQQQQQQQQQQQQQQQ

{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "commands": [
    "recipes.cook.recrod"
  ]
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0QVC1Y678EB1SN1MB

{
  "error": {
    "code": "unknown_command",
    "message": "There's no command named recipes.cook.recrod. Use the exact tool names, with dots. No changes were applied.",
    "details": {
      "commands": [
        "recipes.cook.recrod"
      ]
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0QVC1Y678EB1SN1MB"
  }
}

A person who isn't in the household

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

{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "for_person_id": "per_01JC000000000000000000000Z"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0VAQBMY7JF36NVRC5

{
  "error": {
    "code": "person_not_found",
    "message": "That person isn't in the household. No changes were applied.",
    "details": {
      "person_id": "per_01JC000000000000000000000Z"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0VAQBMY7JF36NVRC5"
  }
}

A trigger that isn't there

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

{
  "trigger_id": "trg_01JC00000000000000000000T1",
  "title": "Nope"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0WZBTBCT9HMM8HCNB

{
  "error": {
    "code": "trigger_not_found",
    "message": "That trigger isn't there any more. No changes were applied.",
    "details": {
      "trigger_id": "trg_01JC00000000000000000000T1"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0WZBTBCT9HMM8HCNB"
  }
}

Change when a trigger acts

at waits until a time of day.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/agent.trigger.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CTCMPCN298BVPM4YXFFH' \
  -d '{
  "trigger_id": "trg_01M6V9CTCG6HY7NK67ENWMSS1Z",
  "when": {
    "kind": "at",
    "time": "19:30"
  }
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/agent.trigger.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CTCMPCN298BVPM4YXFFH",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    trigger_id: "trg_01M6V9CTCG6HY7NK67ENWMSS1Z",
    when: {
      kind: "at",
      time: "19:30",
    },
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/agent.trigger.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CTCMPCN298BVPM4YXFFH

{
  "trigger_id": "trg_01M6V9CTCG6HY7NK67ENWMSS1Z",
  "when": {
    "kind": "at",
    "time": "19:30"
  }
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTCMEXMDG31TGRSWE94P

{
  "result": {
    "trigger_id": "trg_01M6V9CTCG6HY7NK67ENWMSS1Z"
  },
  "version": 320
}

For Rigel#

Rigel's tool for this command is agent_trigger_update. 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