agent-branches API
List agent's branches
Returns the branches of an agent. By default only the live MAIN and CANDIDATE branches are returned; pass `includeInactive=true` to also see DISCARDED history (and any legacy SUPERSEDED rows from before promote stopped producing that status). `applicationId` narrows the result to branches scoped to that application (plus company-wide ones); omit it to validate company-wide access and return every branch visible under the caller's company.
Fork new variant branch
Forks a new CANDIDATE branch, copying a spec into a fresh, independent artifact lineage. The source can be this agent's own lineage (`published`, `draft`, or a specific artifact `version`), ANOTHER agent in the same application (`agent`, copying that agent’s published version or current draft), or a spec document supplied inline (`spec`, e.g. the `agent.spec` of an exported agent file — only the spec is imported; evals, routines, sub-agents and insights in the export are not). Never touches the agent's published pointer — a fork is purely additive until a later promote. Capped at 10 live variants per agent.
Get agent branch
Returns a single branch by id.
Rename agent branch
Renames a branch. Useful for a variant demoted from MAIN by a promote — it's given a generated placeholder name if it still carried the reserved literal name 'main' (see the promote endpoint), and this lets the user replace that with something meaningful. Names are unique per agent; a duplicate answers 409.
Discard variant branch
Abandons a branch: flips it to DISCARDED. The artifact and its version history are retained — nothing is deleted, only the lifecycle status changes. Rejects discarding the MAIN branch; promoting a variant over MAIN is the only supported way to retire a MAIN line.
Preview promoting variant branch
Previews what promoting this variant would do: whether it is stale (the published pointer moved since the branch was forked, so promoting would make main’s draft skip the work main gained in the meantime) and, if so, the semantic changes between the fork base and what is currently published. Promoting itself does not publish — this preview is about what the resulting draft lineage would miss, not about production.
Promote variant branch to MAIN
Promotes a variant branch: makes it the agent's main line by flipping the agent's draft pointer (`Agent.metadata.specArtifactId`) and both branch rows (old MAIN -> CANDIDATE, variant -> MAIN) together. The old MAIN line is demoted, not archived — it keeps its artifact and version history and stays a fully editable variant that can be renamed, edited, promoted back, or deleted. This does **not** publish — `Agent.publishedArtifactId`/`publishedVersion` are left exactly where they were, and production keeps serving whatever was last published until a separate call to the publish endpoint. A stale promote — one whose fork base is no longer what is published — is rejected with 409 unless `acknowledgeSupersede` is `true`.