Edit capsules (HTTP)

When options.edit_capsules = true (under [options] in bmo.toml; legacy [experimental] edit_capsules is copied into options by normalize) and BMO has wired the edit-capsule service (sessions database plus options.data_directory), bmo serve exposes session-scoped routes under /v1/sessions/{id}/edit-capsules. All routes require Bearer authentication like other protected API routes.

How to use this reference

Use these HTTP routes when an external process needs to observe or label edit capsules. Use the native agent tools when you need baseline capture, rollback, or validation behavior, because those workflows are intentionally not mirrored one-for-one over HTTP.

Availability

If edit capsules are disabled in config, handlers respond with 404 and the message edit capsules not enabled.
If the flag is on but the service could not be started (missing DB handle or data directory), handlers respond with 503 and a message that names options.data_directory and the sessions database requirement.

Routes

Method	Path	Purpose
`GET`	`/v1/sessions/{id}/edit-capsules`	List capsules for the session
`POST`	`/v1/sessions/{id}/edit-capsules`	Start a capsule (`StartCapsule`)
`GET`	`/v1/sessions/{id}/edit-capsules/{capsuleId}`	Get one capsule
`PATCH`	`/v1/sessions/{id}/edit-capsules/{capsuleId}`	Set the user label (`user_label` only; does not overwrite `lifecycle_message`)
`DELETE`	`/v1/sessions/{id}/edit-capsules/{capsuleId}`	Delete a capsule record

Request bodies for POST and PATCH reject unknown JSON fields (strict decode).

`POST`: start-only vs native `create_edit_capsule`

POST creates a capsule via StartCapsule only. The new row starts in an applying (or equivalent early) status; it does not run baseline capture, restore the working tree, or finish the manual snapshot flow implemented by the native create_edit_capsule tool.

Use create_edit_capsule when you need that full tool behavior. Use POST when you intentionally open a capsule for a workflow that will drive CaptureBaselines, ApplyFile, validation, commit, or rollback through the coordinator write pipeline.

`user_label` and `lifecycle_message` in responses

user_label — set by explicit label updates (PATCH, update_edit_capsule) and by SetValidationResult when validation passes with a non-empty message (e.g. create_edit_capsule commit label).
lifecycle_message — system-owned: backup failures, validation failure text, dismiss copy, etc. Automation does not overwrite user_label when updating lifecycle text.

Native tools without HTTP equivalents

Rollback, dismiss, and force-rollback are exposed as agent tools (capsule_rollback, capsule_dismiss, etc.), not as these HTTP routes.