Delete a project

maintenance.project.remove

POST/api/v1/households/{household_id}/commands/maintenance.project.remove

Command
Rigel asks first
Applies offline

Deletes the project, its work log and its item links. Its problems, visits and invoices stay, without the project. Documents linked to it stay. Prefer setting status to done or cancelled.

Parameters#

Delete a project: 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.

Delete a project: request body fields
Field	Description
`project_id`stringrequired	A maintenance project ID, such as mpj_01JC0000000000000000000000.

Response#

200 The command was applied.

Delete a project: 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.

Delete a project: 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`	`project_not_found`	A project that isn't there.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`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.

Deletes the project, its log and links, and keeps the problem

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.project.remove' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "project_id": "mpj_01JC00000000000000000000J1"
}'

Request, TypeScript

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

Request, HTTP

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

{
  "project_id": "mpj_01JC00000000000000000000J1"
}

Response, 200

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

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

A project that isn't there

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.project.remove' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "project_id": "mpj_01JC00000000000000000000JX"
}'

Request, TypeScript

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

Request, HTTP

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

{
  "project_id": "mpj_01JC00000000000000000000JX"
}

Response, 404

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

{
  "error": {
    "code": "project_not_found",
    "message": "That project isn't there any more. No changes were applied.",
    "details": {
      "project_id": "mpj_01JC00000000000000000000JX"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R03YYSR4PSN5QEPZF8"
  }
}

For Rigel#

Rigel's tool for this command is maintenance_project_remove. Rigel shows the person what it will do and waits for a yes before running this, because it can't be fixed afterward or it reaches outside the household. The agent guide has the rest.