Rename, recolor or change a calendar

calendar.calendar.update

POST/api/v1/households/{household_id}/commands/calendar.calendar.update

Command
Rigel runs it
Applies offline

Sets only the fields given. Making a calendar the default (is_default true) takes the flag off the old one. The default can't be switched off directly (calendar_is_default): make another calendar the default instead. Whether a calendar is busy-only can't change.

Parameters#

Rename, recolor or change a calendar: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`Idempotency-Key`headerstringoptional	The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Rename, recolor or change a calendar: request body fields
Field	Description
`calendar_id`stringrequired	A calendar ID, such as cal_01JC0000000000000000000000.
`name`stringoptional	A calendar's name, as written, 1–80 characters: "Family", "Nia's school". Unique ignoring case. 1 to 80 characters
`color`one of: calendar-1, calendar-2, calendar-3, calendar-4, calendar-5, calendar-6, calendar-7, calendar-8optional	One of the eight calendar color tokens, calendar-1 to calendar-8.
`person_id`string or nulloptional	Whose calendar it is, or null for a shared one.
`is_default`booleanoptional	true makes it the default calendar.
`is_visible`booleanoptional	Whether it shows in the views by default.
`sort_order`integeroptional	Where it goes in the list. at least 0

Response#

200 The command was applied.

Rename, recolor or change a calendar: response fields
Field	Description
`result`objectrequired	What the command returned, such as the IDs it created.
`version`integerrequired	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.

Rename, recolor or change a calendar: 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`	`person_not_found`	The owner must exist.
`404`	`calendar_not_found`	The calendar must exist.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	`calendar_is_default`	The default can't be switched off.
`409`	`name_taken`	The name can't be another calendar's.
`409`	`idempotency_key_reused`	The 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.

Sets only what's given

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000B",
  "name": "Ben'\''s",
  "color": "calendar-6",
  "is_visible": false,
  "sort_order": 5
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000B",
    name: "Ben's",
    color: "calendar-6",
    is_visible: false,
    sort_order: 5,
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000B",
  "name": "Ben's",
  "color": "calendar-6",
  "is_visible": false,
  "sort_order": 5
}

Response, 200

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

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

A calendar can change its own name's case

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000B",
  "name": "DAVID"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000B",
    name: "DAVID",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000B",
  "name": "DAVID"
}

Response, 200

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

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

Making a calendar the default takes the flag off the old one

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000B",
  "is_default": true
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000B",
    is_default: true,
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000B",
  "is_default": true
}

Response, 200

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

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

The owner can be cleared

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000B",
  "person_id": null
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000B",
    person_id: null,
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000B",
  "person_id": null
}

Response, 200

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

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

Switching off a calendar that isn't the default is fine

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000B",
  "is_default": false
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000B",
    is_default: false,
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000B",
  "is_default": false
}

Response, 200

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

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

The default can't be switched off

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000A",
  "is_default": false
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000A",
    is_default: false,
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000A",
  "is_default": false
}

Response, 409

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

{
  "error": {
    "code": "calendar_is_default",
    "message": "Family is the default calendar. Make another calendar the default instead. No changes were applied.",
    "details": {
      "calendar_id": "cal_01JC000000000000000000000A"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0ZETFXR312B1V4HR6"
  }
}

The name can't be another calendar's

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000B",
  "name": "family"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000B",
    name: "family",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000B",
  "name": "family"
}

Response, 409

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

{
  "error": {
    "code": "name_taken",
    "message": "There's already a calendar called family. No changes were applied.",
    "details": {
      "name": "family"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0WDJ33BYV8KMNE2G3"
  }
}

The owner must exist

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000B",
  "person_id": "per_01JC000000000000000000000Z"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000B",
    person_id: "per_01JC000000000000000000000Z",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000B",
  "person_id": "per_01JC000000000000000000000Z"
}

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0R30DNDQFQ2HDMBW8

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

The calendar must exist

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "calendar_id": "cal_01JC000000000000000000000Z",
  "name": "x"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01JC000000000000000000000Z",
    name: "x",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "calendar_id": "cal_01JC000000000000000000000Z",
  "name": "x"
}

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0AKJGHG6NAWPJRHYS

{
  "error": {
    "code": "calendar_not_found",
    "message": "That calendar isn't there any more. No changes were applied.",
    "details": {
      "calendar_id": "cal_01JC000000000000000000000Z"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0AKJGHG6NAWPJRHYS"
  }
}

Rename and recolor a calendar

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/calendar.calendar.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CSHNCFVQQYV0QSEZ5SFF' \
  -d '{
  "calendar_id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
  "name": "Nia and Theo",
  "color": "calendar-5"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/calendar.calendar.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CSHNCFVQQYV0QSEZ5SFF",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    calendar_id: "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
    name: "Nia and Theo",
    color: "calendar-5",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/calendar.calendar.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CSHNCFVQQYV0QSEZ5SFF

{
  "calendar_id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
  "name": "Nia and Theo",
  "color": "calendar-5"
}

Response, 200

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

{
  "result": {},
  "version": 88
}

For Rigel#

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