Drafts, versions and branches
Know which graph is editable and which saved revision a run will execute
A draft is an editable working copy. A version is a saved pipeline asset revision. A run captures the active saved revision and resolved execution configuration at dispatch time. Editing a draft after dispatch does not rewrite the existing run's snapshot.
Lifecycle
| Action | Effect | Does it execute? |
|---|---|---|
| Accept a graph proposal / edit a node | Changes the draft | No |
| Save a draft | Persists the actor's editable document | No |
| Validate | Checks graph and executable configuration | No |
| Save version | Commits a graph revision | No |
| Activate a version | Selects the saved revision for subsequent launches | No |
| Run | Queues work from the active saved version | Yes |
Creation records an initial version and a draft. HTTP/MCP clients must not assume a later draft save replaces the active version. Studio's launch flow requires saved edits; programmatic execution resolves the active version rather than automatically committing your draft.
Inspect and change versions
In Studio, inspect History, compare versions and review changed nodes, endpoint/capability bindings and write modes. Save a meaningful commit message. When restoring or activating an older version, verify its resource bindings still exist and its target remains appropriate today.
Branches distinguish alternative document histories. A version comparison shows differences; it does not merge them. Undo/redo affects editing state, not completed external writes. Discarding a draft does not cancel a running job.
Example: change a source
- Open the existing pipeline and record its active version ID.
- Edit the ingress binding in the draft to a new accessible source endpoint.
- Validate and inspect the resolved source target; compare against the prior version.
- Save a version, then check that it is the version selected for launch.
- Run a small fixture. Inspect that run's version ID and source results.
A schedule resolves the pipeline's active version when preparing a run; the schedule schema does not pin a specific version ID. Review version activation as an operational change when schedules are enabled.
Public interfaces
HTTP version history: GET /api/v1/projects/<PROJECT_ID>/pipelines/<PIPELINE_ID>/versions (pipelines:read). Create a revision with POST .../versions, a full document and optional branchName/commitMessage (pipelines:write, Idempotency-Key). Activate with POST .../versions/<VERSION_ID>/activate and body containing versionId. Branch creation uses POST .../branches with name and optional sourceVersionId.
The public API also supports full-document replacement with PUT .../pipelines/<PIPELINE_ID> and settings-only PATCH for name, description and tags. These are different actions. The MCP pipeline tools expose draft saving, but no dedicated version-commit or activation tool is currently listed. Use Studio or the HTTP version interface for those steps.