The idea#
An edit is a batch: a list of operations, each one a named command such as track.add or item.move, with its arguments. The whole batch applies or none of it does, and it becomes one revision and one undo step.
Every batch names the base_revision it was planned against. If the project moved on, the core tries to replay your batch on top of the newer revisions. When the changes overlap, it answers E_REVISION_CONFLICT with a text diff of what changed, so you can read it and plan again.
Quick start#
- Read the revision:
project_get, or therevisionof your last edit result. - Send the batch with that
base_revision. Give a new track or item your ownidwhen a later operation in the same batch refers to it. - Use
dry_run: trueto check a batch without saving it. - Use an
idempotency_keywhen you may retry: the same key with the same batch returns the first result, withreplayed: true. The same key with a different batch isE_IDEMPOTENCY_MISMATCH.
The operations are in the command catalogue.
Common mistakes#
- Sending a
base_revisionahead of the project:E_VALIDATION. - Retrying a conflict unchanged. Read the diff first.