Skip to content
Rigel docs
Open Rigel

Link a task to a record in another app

tasks.task.link

POST/api/v1/households/{household_id}/commands/tasks.task.link

  • Command
  • Rigel runs it
  • Applies offline

Links the task to another app's record, such as the furnace in maintenance. Linking twice does nothing. Link documents with the documents app's own command instead. Fails with task_not_found.

Parameters#

Link a task to a record in another app: 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.

Link a task to a record in another app: request body fields
FieldDescription
task_idstringrequired

A task ID, such as tsk_01JC0000000000000000000000.

record_idstringrequired

The other app's record, such as a maintenance task or a recipe.

Response#

200 The command was applied.

Link a task to a record in another app: response fields
FieldDescription
resultobjectrequired

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

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.

Link a task to a record in another app: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404task_not_foundA missing task.
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.

Links a record

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

{
  "task_id": "tsk_01JC000000000000000000000A",
  "record_id": "fil_01JC00000000000000000000R1"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R089DF5231NPMSG5HT

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

Linking twice does nothing

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

{
  "task_id": "tsk_01JC000000000000000000000A",
  "record_id": "fil_01JC00000000000000000000R1"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R073XMYPHNFE0Q1AKM

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

A record that is not there is still linked

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

{
  "task_id": "tsk_01JC000000000000000000000A",
  "record_id": "fil_01JC00000000000000000000ZZ"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R01G5RCFNPF2JV8W53

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

A missing task

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

{
  "task_id": "tsk_01JC000000000000000000000Z",
  "record_id": "fil_01JC00000000000000000000R1"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0Y7F2X01VB5KJCQV9

{
  "error": {
    "code": "task_not_found",
    "message": "That task isn't there any more. No changes were applied.",
    "details": {
      "task_id": "tsk_01JC000000000000000000000Z"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0Y7F2X01VB5KJCQV9"
  }
}

Link a task to a record in another app

record_id can be any record, such as a recipe.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/tasks.task.link' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CT435XKAG3F9008EM1GW' \
  -d '{
  "task_id": "tsk_01M6V9CT2Z01QVT17DRMSXTW4W",
  "record_id": "rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/tasks.task.link", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CT435XKAG3F9008EM1GW",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    task_id: "tsk_01M6V9CT2Z01QVT17DRMSXTW4W",
    record_id: "rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/tasks.task.link HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CT435XKAG3F9008EM1GW

{
  "task_id": "tsk_01M6V9CT2Z01QVT17DRMSXTW4W",
  "record_id": "rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CT43JFH13WAZNPJR1BY0

{
  "result": {},
  "version": 247
}

For Rigel#

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