timeline.promote · Umwelt docs

Reference/Commands/timeline.promote

timeline.promotecommandsince 0.1

Promotes a draft into its parent: all of its work becomes part of the parent at once.

Command lineTypeScript.NET

Request

umwelt call story.umw timeline.promote '{
  "projectId": "ball",
  "timelineId": "chapter-2"
}'

Request

const result = await client.timelinePromote({ projectId: 'ball', timelineId: 'chapter-2' });

Request

var result = engine.TimelinePromote(new TimelineRef { ProjectId = "ball", TimelineId = "chapter-2" });

Response

{
  "kind": "draft",
  "id": "chapter-2",
  "status": "promoted",
  "projectId": "ball",
  "label": "Chapter 2",
  "baseVersion": 16,
  "closedAt": "2026-11-11T18:21:58.6788929Z",
  "createdAt": "2026-11-11T18:21:58.6687174Z",
  "depth": 1,
  "headVersion": 17,
  "maxTick": 11,
  "parentTimelineId": "main"
}

Payload

Field	Type	Description
`projectId`required	string	The project to write to.
`timelineId`required	stringdefault "main"	The timeline to write to.

Result

Field	Type	Description
`id`always	string	The timeline’s id. Main is always `main`.
`projectId`always	string	The project it belongs to.
`kind`always	"main" \| "draft"	`main` or `draft`.
`status`always	"active" \| "promoted" \| "discarded"	`active`, `promoted` or `discarded`. Only an active timeline accepts writes.
`label`	string	Its label.
`parentTimelineId`	string	The timeline it branched from: `main` or another draft. Absent for main.
`depth`always	integer	Drafts from main down to it: 0 for main, 1 for a draft of main, at most 4.
`baseVersion`	integer	The parent’s head when it was opened. Absent for main.
`headVersion`always	integer	The version of its latest commit, or its base when it has none.
`maxTick`always	integer	The highest tick it sees.
`createdAt`always	string	When it was opened (UTC).
`closedAt`	string	When it was promoted or discarded.
`purgedAt`	string	When its rows were purged.

Rules

Only if the parent did not move. The parent’s head must still be the draft’s baseVersion. Otherwise it fails with VERSION_CONFLICT and the draft is left intact: rebase it, discard it, or open a new one.

No earlier read changes. Every row keeps its version, so reads of the parent at earlier versions answer as before.

Children are handed over. Drafts opened from the promoted one move to its parent, and see exactly what they saw.

Errors

VERSION_CONFLICTThe parent moved since the draft was opened. details has baseVersion, parentTimelineId and parentHeadVersion.

NOT_FOUNDThe project or draft does not exist.

INVALID_STATEThe timeline is main, or the draft or its parent is not active.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also