Creating and editing documents
This is the writing section of the usage guide. Call getDocs with { "section": "writing" } to read it on an instance.
Available only when writeDoc and editDoc are in your tool list. For a
member they work on the member's own home and ordinary shared projects with an
explicit write grant. A read-only shared grant refuses the write, and another
member's home reads as not found. For an admin or staff user they work on
ordinary shared projects only, need no per-project grant, and are offered only
when the instance has shared-project writing on. A member's home refuses their
write as forbidden:member_role_required. Project permissions
are checked again on every change.
The loop is always the same:
readDocthe document. The result carries an opaqueversionfor the exact bytes you read.- Call
writeDoc(replace the whole file) oreditDoc(replace one exact passage) passing thatversionasexpectedVersion. The two tools spell itexpectedVersion;readDoc's own paging parameter is spelledversion. - To CREATE a new document, call
writeDocwith NOexpectedVersion. It is refused if anything already exists at that path. It never overwrites blind.
Both tools need an operationId you invent (a UUID is ideal) and a one-line
reason. Retrying with the same id AND the same arguments returns the original
result instead of writing twice; the same id with different arguments is a
conflict, so use a fresh id for a new change.
There is no history, no versioning and no undo. A replacement discards the
previous text permanently, and nothing here can bring it back. Read before you
write, change the smallest thing that does the job, and prefer editDoc over
rewriting a whole document.
A stale expectedVersion means somebody or something changed the file after
you read it. That is recoverable: readDoc again, decide whether your change
still makes sense against the new text, and retry with the new version and a
fresh operationId. Never retry by dropping the version.
Limits: UTF-8 text only, in .md, .txt, .csv, .json, .xml, .yaml or
.yml files, up to 1 MiB per document. editDoc's oldString must match the
current file exactly and occur exactly once. Include surrounding lines to make
it unique rather than retrying a short string.