Restore an earlier version of a document
documents.version.restore
POST/api/v1/households/{household_id}/commands/documents.version.restore
- Command
- Rigel runs it
- Applies offline
Makes an earlier version's text and title current. The text it replaces is saved first as a restore version, so the restore can itself be undone by restoring that.
Parameters#
| Field | Description |
|---|---|
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.
| Field | Description |
|---|---|
version_idstringrequired | A document version ID, such as dcv_01JC0000000000000000000000. |
Response#
200 The command was applied.
| Field | Description |
|---|---|
resultobjectrequired | What the command returned, such as the IDs it created. |
result.content_versionintegerrequired | The document's content_version after the change. |
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.
| 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 | version_not_found | A version that is gone. |
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.
Restoring saves the current text and sets the old
Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.version.restore' \
-H "Cookie: rigel_session=$RIGEL_SESSION" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
-d '{
"version_id": "dcv_01JC0000000000000000000001"
}'Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.version.restore", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
},
body: JSON.stringify({
version_id: "dcv_01JC0000000000000000000001",
}),
});
const data = await response.json();Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.version.restore HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA
{
"version_id": "dcv_01JC0000000000000000000001"
}Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0TKW35Y7QK1VSDCKR
{
"result": {
"content_version": 4
},
"version": 1
}A version that is gone
Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.version.restore' \
-H "Cookie: rigel_session=$RIGEL_SESSION" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
-d '{
"version_id": "dcv_01JC0000000000000000000001"
}'Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.version.restore", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
},
body: JSON.stringify({
version_id: "dcv_01JC0000000000000000000001",
}),
});
const data = await response.json();Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.version.restore HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA
{
"version_id": "dcv_01JC0000000000000000000001"
}Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0K3SY5PE6N23WRP55
{
"error": {
"code": "version_not_found",
"message": "That version isn't there any more. No changes were applied.",
"details": {
"version_id": "dcv_01JC0000000000000000000001"
},
"recovery": "Read the current state, then send a command that fits it.",
"request_id": "req_01K9D9S2R0K3SY5PE6N23WRP55"
}
}Restore an earlier version
The text it replaces is saved first, so the restore can be undone the same way.
Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.version.restore' \
-H "Cookie: rigel_session=$RIGEL_SESSION" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: cmd_01M6V9CTAZA2R962KYK63PWHY2' \
-d '{
"version_id": "dcv_01M6V9CTAM33T4YK1TF4F53B8D"
}'Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.version.restore", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Idempotency-Key": "cmd_01M6V9CTAZA2R962KYK63PWHY2",
Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
},
body: JSON.stringify({
version_id: "dcv_01M6V9CTAM33T4YK1TF4F53B8D",
}),
});
const data = await response.json();Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.version.restore HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CTAZA2R962KYK63PWHY2
{
"version_id": "dcv_01M6V9CTAM33T4YK1TF4F53B8D"
}Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTAZWWNNEPEQ31QNQDJV
{
"result": {
"content_version": 5
},
"version": 311
}For Rigel#
Rigel's tool for this command is documents_version_restore. Rigel runs this on its own, then says what it did. The agent guide has the rest.