Skip to content
Rigel docs
Open Rigel

Make targeted changes to a document

documents.document.edit

POST/api/v1/households/{household_id}/commands/documents.document.edit

  • Command
  • Rigel runs it
  • Applies offline

Applies changes to a Markdown or HTML document in order: replace an exact passage ({find, replace}), insert at the end of a heading's section ({after_heading, insert}), or add to the end ({append}). Prefer this to a rewrite for small changes: it merges with people typing. All or nothing: if any edit can't be applied (passage_not_found, with edit_index saying which, counting from 0), nothing changes. Rigel's edits save the earlier text as a version, unless Rigel made a version in the last 10 minutes. Refused for uploaded files (document_is_file).

Parameters#

Make targeted changes to a document: 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.

Make targeted changes to a document: request body fields
FieldDescription
document_idstringrequired

A document ID, such as doc_01JC0000000000000000000000.

editsarray of one of 3 shapesrequired

The changes, applied in order.

1 to 100 items
Shape 1, with find, replace
edits[].findstringrequired

The exact text to replace. The first occurrence is replaced.

at least 1 character
edits[].replacestringrequired

What to put in its place; empty deletes the passage.

Shape 2, with after_heading, insert
edits[].after_headingstringrequired

The heading's text, matched ignoring case, surrounding space and any leading # marks. The first matching heading is used.

at least 1 character
edits[].insertstringrequired

Text to add. In Markdown it goes at the end of that heading's section, before the next heading of the same or a higher level. In HTML it goes right after the heading element.

Shape 3, with append
edits[].appendstringrequired

Text to add at the very end of the document.

Response#

200 The command was applied.

Make targeted changes to a document: response fields
FieldDescription
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.

Make targeted changes to a document: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404passage_not_found
  • A passage that isn't there changes nothing.
  • A heading that isn't there.
404document_not_foundA document that is gone.
404not_foundThe household doesn't exist, or you aren't a member of it.
409document_is_fileAn uploaded file.
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.

Replacing the first occurrence of a passage

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "cat",
      "replace": "dog"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        find: "cat",
        replace: "dog",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "cat",
      "replace": "dog"
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R09CE3KSJBSJ30ZSAZ

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

Inserting at the end of a heading's section

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "food",
      "insert": "Pasta."
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        after_heading: "food",
        insert: "Pasta.",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "food",
      "insert": "Pasta."
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0NFSM0TBQ8GMF7FG2

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

A heading given with its # marks, in the last section

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "## Sights ",
      "insert": "Museum."
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        after_heading: "## Sights ",
        insert: "Museum.",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "## Sights ",
      "insert": "Museum."
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0HBQH3C8D4PSVJBYP

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

Appending

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "append": "Two"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        append: "Two",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "append": "Two"
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0X3FE4EX38GFSRAKB

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

Several edits apply in order

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "a",
      "replace": "b"
    },
    {
      "find": "b",
      "replace": "c"
    },
    {
      "append": "\nd"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        find: "a",
        replace: "b",
      },
      {
        find: "b",
        replace: "c",
      },
      {
        append: "\nd",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "a",
      "replace": "b"
    },
    {
      "find": "b",
      "replace": "c"
    },
    {
      "append": "\nd"
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0WDS71Z4B8NX9M1HG

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

Inserting after an HTML heading

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "guide",
      "insert": "<p>New</p>"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        after_heading: "guide",
        insert: "<p>New</p>",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "guide",
      "insert": "<p>New</p>"
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R000R9B8GD4E9XRR86

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

A person's edit saves no version

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "a",
      "replace": "x"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        find: "a",
        replace: "x",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "a",
      "replace": "x"
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R04HW459BSGC9C1XEW

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

A passage that isn't there changes nothing

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "a",
      "replace": "x"
    },
    {
      "find": "zzz",
      "replace": "y"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        find: "a",
        replace: "x",
      },
      {
        find: "zzz",
        replace: "y",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "find": "a",
      "replace": "x"
    },
    {
      "find": "zzz",
      "replace": "y"
    }
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R07FTMFKYXB9MQF841

{
  "error": {
    "code": "passage_not_found",
    "message": "Edit 1: the passage \"zzz\" isn't in the document. Nothing was changed. No changes were applied.",
    "details": {
      "edit_index": 1,
      "edit": {
        "find": "zzz",
        "replace": "y"
      }
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R07FTMFKYXB9MQF841"
  }
}

A heading that isn't there

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "Hotels",
      "insert": "x"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        after_heading: "Hotels",
        insert: "x",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "after_heading": "Hotels",
      "insert": "x"
    }
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0B46HT16ZX487GD1E

{
  "error": {
    "code": "passage_not_found",
    "message": "Edit 0: there's no heading \"Hotels\". Nothing was changed. No changes were applied.",
    "details": {
      "edit_index": 0,
      "edit": {
        "after_heading": "Hotels",
        "insert": "x"
      }
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0B46HT16ZX487GD1E"
  }
}

An uploaded file

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC000000000000000000000F",
  "edits": [
    {
      "append": "x"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC000000000000000000000F",
    edits: [
      {
        append: "x",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC000000000000000000000F",
  "edits": [
    {
      "append": "x"
    }
  ]
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0MY86ZZKSGYB985QZ

{
  "error": {
    "code": "document_is_file",
    "message": "That document is an uploaded file, so it has no text to write. Its extracted text can be saved with documents.document.save_text. No changes were applied.",
    "details": {
      "document_id": "doc_01JC000000000000000000000F"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0MY86ZZKSGYB985QZ"
  }
}

A document that is gone

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "append": "x"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    edits: [
      {
        append: "x",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "edits": [
    {
      "append": "x"
    }
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0M8CRG7ZYF9WEZBJ6

{
  "error": {
    "code": "document_not_found",
    "message": "That document isn't there any more. No changes were applied.",
    "details": {
      "document_id": "doc_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0M8CRG7ZYF9WEZBJ6"
  }
}

Make targeted changes to a document

A passage to replace, text to add under a heading, or text to append. Edits merge with people typing.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CTAHHPPAK5Y29SJJ87CQ' \
  -d '{
  "document_id": "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
  "edits": [
    {
      "find": "Nia is choosing the color.",
      "replace": "Nia is choosing the color from three samples."
    },
    {
      "after_heading": "Shelves",
      "insert": "Ask the carpenter about a bench seat at the window."
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CTAHHPPAK5Y29SJJ87CQ",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
    edits: [
      {
        find: "Nia is choosing the color.",
        replace: "Nia is choosing the color from three samples.",
      },
      {
        after_heading: "Shelves",
        insert: "Ask the carpenter about a bench seat at the window.",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CTAHHPPAK5Y29SJJ87CQ

{
  "document_id": "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
  "edits": [
    {
      "find": "Nia is choosing the color.",
      "replace": "Nia is choosing the color from three samples."
    },
    {
      "after_heading": "Shelves",
      "insert": "Ask the carpenter about a bench seat at the window."
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTAHXF0M05MNSK60ASGD

{
  "result": {
    "content_version": 2
  },
  "version": 306
}

Edit a passage that isn't there

Nothing changes when any edit can't be applied. edit_index says which one failed.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.edit' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CTAK79Z059ACQ55V83NZ' \
  -d '{
  "document_id": "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
  "edits": [
    {
      "find": "A passage that isn'\''t there.",
      "replace": "Nothing."
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.edit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CTAK79Z059ACQ55V83NZ",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
    edits: [
      {
        find: "A passage that isn't there.",
        replace: "Nothing.",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.edit HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CTAK79Z059ACQ55V83NZ

{
  "document_id": "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
  "edits": [
    {
      "find": "A passage that isn't there.",
      "replace": "Nothing."
    }
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01M6V9CTAKTDPB80QHY2PGTS96

{
  "error": {
    "code": "passage_not_found",
    "message": "Edit 0: the passage \"A passage that isn't there.\" isn't in the document. Nothing was changed. No changes were applied.",
    "details": {
      "edit_index": 0,
      "edit": {
        "find": "A passage that isn't there.",
        "replace": "Nothing."
      }
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01M6V9CTAKTDPB80QHY2PGTS96"
  }
}

For Rigel#

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