Journeys / REFERENCE

Save or branch a journey version

Save a draft or create a branch. Enhanced contracts require contentContractVersion:2, expectedRevision for an existing source, and requestId for creation. Published versions are immutable and edits create a draft.

POST/api/v1/journeys/{journeyId}/versions

Permissions journeys:write

Parameters

Name	Description
`X-Luma-Workspace-Host`header · required	Your workspace host, e.g. acme.lumi-cx.com. Required on api.lumi-cx.com. This header never grants access: the Bearer key must belong to the selected workspace.
`journeyId`path · required	Record identifier in this workspace.

Request body

Field	Type & description
`content`required	object Complete macro (schema: 2) or micro (schema: micro-v1) document. Read-modify-write the returned document to retain all fields. Micro content includes scenarios, step messages, choices, connector rules, timing and support documents.
`versionId`	string
`parentVersionId`	string
`label`	string
`expectedRevision`	integer
`contentContractVersion`	integer
`requestId`	string Unique request identifier required for enhanced creation/restoration; reuse only for retrying the identical request.
`allowStaleSource`	boolean

Responses

200 Successful operation

{
  "ok": true,
  "version": {
    "id": "00000000-0000-4000-8000-000000000001",
    "journeyId": "00000000-0000-4000-8000-000000000001",
    "label": "example",
    "parentVersionId": "00000000-0000-4000-8000-000000000001",
    "content": {
      "schema": 2,
      "stages": [
        {
          "id": "onboarding",
          "titleEn": "Onboarding",
          "titleAr": "",
          "microJourneyPairs": []
        }
      ],
      "rows": [],
      "cells": {}
    },
    "createdBy": "example",
    "createdAt": "2026-09-26T09:00:00Z",
    "updatedAt": "2026-09-26T09:00:00Z",
    "publishedAt": "2026-09-26T09:00:00Z",
    "revision": 1,
    "sourceRevision": 1,
    "legacyOrigin": "example",
    "diagnostics": [
      {
        "severity": "example",
        "message": "example"
      }
    ]
  }
}

400 Invalid request

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

401 Missing, invalid, expired, revoked or wrong-workspace key

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

403 Required key permission missing, module unavailable, or workspace suspended

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

404 Record, workspace or route not found

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

409 Version changed or the resource is locked

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

429 Rate limit exceeded; respect Retry-After

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

502 Upstream or unexpected server error

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}