API - change sets and safe edits
Propose, preview, apply or discard plan edits as change sets with conflict detection, and a worked example of an agent editing a plan safely with curl.
A change set is a proposed list of RFC 6902 operations against one plan version. Proposing it changes nothing: you get a readable diff and a before and after simulation summary. Then you apply or discard it.
| Route | Purpose |
|---|---|
POST /plans/{id}/change-sets |
Propose. Nothing is written to the plan. |
GET /plans/{id}/change-sets, GET /change-sets/{id} |
List and read. |
POST /change-sets/{id}/apply |
Apply atomically. Writes a plan version attributed to the caller. |
POST /change-sets/{id}/discard |
Drop it. |
POST /plans/{id}/preview |
The same what-if without storing a change set. |
If the plan changed after the proposal, apply fails with 409 CHANGESET_CONFLICT (details.baseVersion,
details.currentVersion) and nothing is merged. Proposing against a stale baseVersion, or with an operation whose path
does not exist, fails at once with VERSION_CONFLICT or PATCH_CONFLICT. Undo is
POST /plans/{id}/versions/{n}/restore.
Worked example
The user asks an agent: “Can I spend 500 more a month on dining?” The agent has a read plus write key. The numbers are
illustrative.
-
Read the plan and note its version, and the id of what to change.
api $GLIDEWORTH/api/v1/plans/plan-main/expenses/exp-living -i | egrep -i '^etag|"amount"' # ETag: "4" amount: { value: 5200, basis: "real" }, frequency: "monthly" -
Ask “what if” first. Nothing is stored.
api -X POST $GLIDEWORTH/api/v1/plans/plan-main/preview -d '{ "ops": [{ "op": "replace", "path": "/expenses/[id=exp-living]/amount/value", "value": 5700 }] }' -
Propose it against the version that was read.
api -X POST $GLIDEWORTH/api/v1/plans/plan-main/change-sets -d '{ "summary": "Living expenses +500/month (dining)", "rationale": "User asked about spending 500/month more on dining", "baseVersion": 4, "ops": [{ "op": "replace", "path": "/expenses/[id=exp-living]/amount/value", "value": 5700 }] }' -
Show the user the changes and the before and after. Apply only after they agree.
api -X POST $GLIDEWORTH/api/v1/change-sets/cs_9f2c.../apply -
To undo, restore the earlier version, which writes it as a new one.
api -X POST $GLIDEWORTH/api/v1/plans/plan-main/versions/4/restore -d '{}'
If someone edited the plan between steps 3 and 4, the apply is refused with CHANGESET_CONFLICT. Re-read and propose
again. The same flow over MCP is in MCP examples.
Last checked against the code on .