Skip to main content
Edit the saved record after reading its current revision and the schema for its kind. A record update is guarded by --expect REVISION; a stale revision means someone changed it since your read. Read again and reconsider your proposed change rather than replaying it against the newer record.
The path is fictional. Use a real returned ID or canonical path. --body alone is not a sufficient edit preflight because it omits the revision and structured fields. A person or other authored record needs the fields required by its current schema, including a description. To create one, save a schema-valid JSON object and give the operation an explicit request key:

​
Choose the smallest complete update

set changes supplied structured fields, and --unset clears optional fields permitted by the schema. Its --input file is a flat field object. For example, description.json can contain {"description":"An engineer at Meridian Labs."}:
patch applies a contextual change to the Markdown body. Its file uses Codex patch syntax, including *** Begin Patch, *** Update File: CANONICAL_PATH, context lines and *** End Patch. The path in the patch must match the selected record. write replaces the entire body, so use it only when that complete replacement is intended.
These commands illustrate successive example revisions; take each actual revision from the preceding response, and run only the operation that fits the record. --patch-file - and --body-file - read standard input. A body operation can also supply --fields @fields.json to update structured fields atomically with the body. The email-to-citation example shows that full shape. Fields omitted from set or --fields stay unchanged. But a supplied array or map replaces its whole value. When updating roles, relationships, citations or field_citations, copy every existing entry you intend to keep, adjust indexed citation paths for the final array, and check that every [@key] in the resulting body has a binding. The CLI expects flat field JSON; its HTTP request builder adds the set envelope. Do not place {"set":{...}} in the input file. Keep a request key for an identical retry if the response is uncertain. If you change the payload or read a new revision after a conflict, choose a new key. The service also checks typed references and cited sources against records owned by the authenticated person; schema-valid JSON alone cannot establish that an ID exists or is accessible. Knowledge and work explains record kinds and identity, while sources and citations explains evidence bindings.