timeline.openDraft · Umwelt docs

Reference/Commands/timeline.openDraft

timeline.openDraftcommandsince 0.1

Opens a draft: a timeline apart from main, or from another draft, that sees its parent as it is now.

Command lineTypeScript.NET

Request

umwelt call story.umw timeline.openDraft '{
  "projectId": "ball",
  "id": "chapter-2",
  "label": "Chapter 2"
}'

Request

const result = await client.timelineOpenDraft({ projectId: 'ball', id: 'chapter-2', label: 'Chapter 2' });

Request

var result = engine.TimelineOpenDraft(new OpenDraftInput
{
    ProjectId = "ball",
    Id = "chapter-2",
    Label = "Chapter 2",
});

Response

{
  "kind": "draft",
  "id": "chapter-2",
  "status": "active",
  "projectId": "ball",
  "label": "Chapter 2",
  "baseVersion": 14,
  "createdAt": "2026-11-11T18:21:58.6687174Z",
  "depth": 1,
  "headVersion": 14,
  "maxTick": 10,
  "parentTimelineId": "main"
}

Payload

Field	Type	Description
`projectId`required	string	The project to write to.
`id`	string	Its id. Generated when absent; `main` is not valid.
`label`	string	Its label, such as “Day 12”.
`baseTimelineId`	string	The parent: `main` (the default) or an active draft.

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

Invisible until promoted. Writes to the draft are seen only by reads of the draft, and of drafts opened from it.

At most four deep. A draft of main has depth 1; drafts nest down to depth 4.

Errors

VALIDATION_FAILEDThe parent is already four drafts deep.

NOT_FOUNDThe project or the parent does not exist, or the parent was purged.

CONFLICTA timeline with that id exists.

INVALID_STATEThe parent was promoted or discarded.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also