timeline.discard · Umwelt docs

Reference/Commands/timeline.discard

timeline.discardcommandsince 0.1

Closes a draft without promoting it. It stays readable by its id, and invisible to every other read.

Command lineTypeScript.NET

Request

umwelt call story.umw timeline.discard '{
  "projectId": "ball",
  "timelineId": "other-ending"
}'

Request

const result = await client.timelineDiscard({ projectId: 'ball', timelineId: 'other-ending' });

Request

var result = engine.TimelineDiscard(new DiscardPayload { ProjectId = "ball", TimelineId = "other-ending" });

Response

{
  "kind": "draft",
  "id": "other-ending",
  "status": "discarded",
  "projectId": "ball",
  "label": "Another ending",
  "baseVersion": 17,
  "closedAt": "2026-11-11T18:21:58.6868871Z",
  "createdAt": "2026-11-11T18:21:58.6818065Z",
  "depth": 1,
  "headVersion": 18,
  "maxTick": 12,
  "parentTimelineId": "main"
}

Payload

Field	Type	Description
`projectId`required	string	The project to write to.
`purge`	booleandefault false	Also remove its rows, as `timeline.purge` does, in the same call.
`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

Its ids stay reserved. Until the draft is purged, its event, record and transition ids cannot be used elsewhere. To replay the same work with the same ids, discard with purge: true.

Nothing you did not name. A draft with an active descendant cannot be discarded.

Errors

NOT_FOUNDThe project or draft does not exist.

INVALID_STATEThe timeline is main, the draft is not active, or drafts depend on it (details.descendants).

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also