> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Journey

> Update an SMS welcome journey definition.

Updates only the supplied fields. Send the complete replacement array when changing `steps`. Status changes also update holds on active enrollments.

Declares the `journeys.write` scope. Authenticate with `X-Api-Key`; see [Authentication](/api-reference/authentication).

Authoring follows the [API key requirements and retry rules](/api-reference/v2/journeys/create-journey#api-key-requirements). Restricted keys may submit an exact status-only stop body; adding any other field makes the request an authoring operation.

## Path Parameters

<ParamField path="journey_id" type="string" required>
  Journey ID returned by create or list. Use a valid journey ID; malformed IDs currently return an unexpected error.
</ParamField>

## Body Parameters

<ParamField body="name" type="string">
  New nonempty journey name.
</ParamField>

<ParamField body="trigger" type="object">
  Replacement trigger group. An empty value resets the trigger to an empty AND group.
</ParamField>

<ParamField body="priority" type="integer">
  New routing priority.
</ParamField>

<ParamField body="steps" type="array of objects">
  Complete replacement step array, using the same format as create.
</ParamField>

<ParamField body="startStepId" type="string">
  New starting step. If omitted, the existing value is retained. A nonempty replacement steps array must still contain that existing start step.
</ParamField>

<ParamField body="status" type="string">
  draft, active, paused, or archived. Any other value is rejected. Clears the pause reason and updates enrollment holds.
</ParamField>

Activation is checked against the result of the update, not the submitted fields: a journey that ends active must have a nonempty steps array and a start step contained in it. [Update Journey Status](/api-reference/v2/journeys/update-journey-status) applies the same checks to the stored journey.

## Response

The `journey` object uses camelCase: `id`, integer `accountId`, `name`, `trigger`, `priority`, `steps`, `startStepId`, `status`, `pauseReason`, `createdAt`, and `updatedAt`. The trigger can be null. Each step contains `stepId`, `name`, `stepType`, `config`, and nullable `nextStepId`. Pause reasons and absent timestamps can be null.

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Journey updated successfully",
    "journey": {
      "id": "664f1a2b3c4d5e6f7a8b9c0d",
      "accountId": 101,
      "name": "Updated welcome",
      "trigger": {
        "operator": "AND",
        "conditions": [],
        "groups": []
      },
      "priority": 0,
      "steps": [
        {
          "stepId": "done",
          "name": "Exit",
          "stepType": "exit",
          "config": {},
          "nextStepId": null
        }
      ],
      "startStepId": "done",
      "status": "draft",
      "pauseReason": null,
      "createdAt": "2026-09-21T10:00:00",
      "updatedAt": "2026-09-21T10:00:00"
    }
  }
  ```
</ResponseExample>

## Errors

| HTTP | Code          | Meaning                                                                                                                   |
| ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 400  | May be absent | Request body is not a JSON object, `name` is not a string, or `priority` is not an integer; read `error`.                 |
| 400  | May be absent | Invalid name, trigger, steps, or routing; read `error`.                                                                   |
| 400  | May be absent | `status` is not draft, active, paused, or archived; read `error`.                                                         |
| 400  | May be absent | The update leaves the journey active with no steps, or with no start step contained in the resulting steps; read `error`. |
| 404  | May be absent | The journey does not exist or belongs to another account.                                                                 |

Authoring may also return the policy, conflict, or availability errors documented under [Create Journey](/api-reference/v2/journeys/create-journey#errors-and-retry).