| to | No | move: the whole new location including the name, e.g. wiki/archive/attention.md; a folder's link moves it into that folder. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too. | |
| from | No | move: the document or directory's whole location, e.g. wiki/attention.md. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too. | |
| name | No | move: the new last segment, to rename in place, e.g. self-attention.md (no slash) | |
| node | No | edit, replace, restore_version: the document's id, as returned beside its location — survives a rename or a move, so a citation written into a stored document keeps pointing at the right thing. Give this OR location, never both. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too. | |
| seat | No | the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent | |
| span | No | edit: a block's span id (search within, browse action=spans): new_string replaces that one block, or, with old_string, old_string inside it; the rest of the document is not read back to you | |
| action | Yes | what to do; each action takes the arguments its line names | |
| append | No | edit: text to add at the end of the document, or of `section`, instead of replacing anything | |
| commit | No | restore_version: the version's commit hash, as browse action=versions lists it (any lowercase prefix of at least 7 hex characters that names one) | |
| content | No | replace: the whole document. Set metadata with YAML frontmatter at the top of `content`: `type` (one of: meeting-notes, playbook, spec, brand-asset, web-clip, contract, misc — anything else becomes misc), `title`, `summary`, and `tags` as a list. `tags` is the write-side spelling of what the listing tools call `label`. `status` takes `active` or `inactive` and is not a label: `inactive` retires a document — search and listings stop showing it, while whoever may write it still opens it by location or node, and removing the line brings it back. Omit it unless you mean to retire something. `aliases` (a list, or one name) are other names search how=titles finds the document by; a [[link]] still needs its file name or title. Any other key you write (`sources`, …) is kept as written and comes back on read; key order may change. A block that does not parse as YAML is refused, naming the line, and nothing is written: quote a value that contains ": " (summary: "a: b"). | |
| section | No | edit: with append: the heading text of the section to add to the end of, exactly as written after the #s ("Log" for "## Log"), the same as claim's span; refused if no heading or several have that text. Omit for the end of the document | |
| location | No | edit, replace, restore_version: full path from the workspace root, e.g. "handbook/vendor/acme.md". Give this OR node. A path is what a person reads; a node is what survives somebody reorganizing. · restore: full path from the workspace root, e.g. "handbook/vendor/acme.md" (as printed by browse action=documents or search). A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too. | |
| acting_as | No | an agent identity below you (its id, from identity_write action=spawn) to make this one call as, with that agent's narrower access; for a helper whose session signs in as its person | |
| new_string | No | edit: what to put in its place | |
| old_string | No | edit: exact text to replace — must appear in the current body (with new_string; not with append) | |
| replace_all | No | edit: replace every occurrence (default: refuse if more than one) | |
| override_claim | No | edit: write even though another agent has CLAIMED the section you are changing. Logged, and they will see it. Default: refuse and name the holder. · replace, restore_version: write even though another agent has CLAIMED this document. Logged, and they will see it. Default: refuse and name the holder. | |
| expected_commit | No | edit: the document head you read at (read action=document prints it; any lowercase prefix of at least 7 hex characters). Refuses if that document has changed since. · replace: the document head you read at (read action=document prints it; any lowercase prefix of at least 7 hex characters). Refuses if that document has changed since. Omit to replace whatever is there now. · restore_version: the document head you read at (read action=document prints it; any lowercase prefix of at least 7 hex characters). Refuses if that document has changed since. Omit to restore over whatever is there now. | |
| idempotency_key | No | Any unique string you choose for this write, e.g. a UUID. If you retry the call with the same key and the same arguments, the first answer is returned and nothing is done twice. Reusing a key for a different request is refused. Keys are kept 24 hours. | |
| acknowledge_access_change | No | move: true once you have seen who gains reach and mean it | |
