> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update journey node
> Apply a partial update to a single journey node, located by its server-assigned id, with JSON Merge Patch.
**Beta.** The Journeys API is in beta. Endpoints and response fields can still change.
## Overview
Update a single node within an existing [Journey](/docs/en/journeys-overview). The request is a [JSON Merge Patch (RFC 7396)](https://datatracker.ietf.org/doc/html/rfc7396): send only the node fields you want to change, and the rest of the node, along with the rest of the journey graph, is left unchanged.
Prefer this endpoint over [Update journey](/reference/update-journey) when you only need to change one node. The journey-level PATCH replaces the entire `nodes` array wholesale, so it requires re-sending every node with its `id`. This endpoint touches just the addressed node and preserves in-flight users on the others.
***
## How to use this API
Authenticate with your [App API Key](/docs/en/keys-and-ids). The authenticated key must have permission to update journeys. Find the journey `id` and the node `id` from a prior [View journey](/reference/view-journey) fetch.
Send only the fields to change. Node fields follow the same schema and validation as [Create journey](/reference/create-journey). For example, to shorten a `wait` node's delay:
```json theme={null}
{
"duration_seconds": 43200
}
```
### Merge patch behavior
The request body is merged onto the addressed node:
* **A field you send replaces the current value.** Omitted fields are untouched.
* **A `null` value clears a nullable field.** Send `"expiration": null` on a `wait_until` node to wait indefinitely.
* **Arrays are replaced as a unit.** `branches` and `windows` are not merged element-wise. Send the full array you want.
* A node's `kind` and its server-assigned `id` cannot be changed. A node keeps its kind for the life of its `id`, so changing the `kind` is rejected (`send_push`, `send_email`, and `send_sms` count as different kinds).
### Optimistic concurrency
To avoid overwriting a concurrent change, pass the `concurrency_key` returned by a prior [View journey](/reference/view-journey) fetch. If the journey has changed since that fetch, the request is rejected with `409 journey-stale` and nothing is written. Omit `concurrency_key` to skip the check.
The key covers the whole journey, not just the addressed node, so a concurrent edit to any part of the journey rejects the request. `concurrency_key` is not merged onto the node.
Treat `concurrency_key` as an opaque token: read it from the journey you are editing and send it back unchanged. Do not construct, parse, or compare it yourself.
```json theme={null}
{
"duration_seconds": 43200,
"concurrency_key": "dcae4794fee16e450e448e37a6f8d0a5a7335755ff8cc76606e3d04b2f574e46"
}
```
### Editing an active journey
The same active-journey rules as [Update journey](/reference/update-journey#editing-an-active-journey) apply. An edit that would strand in-flight users (for example, changing a branching node's branches) returns `400` with a field-level error.
## Response
A successful request returns `200 OK` with the full updated journey, including server-assigned `id` fields and a `concurrency_key`. Pass that `concurrency_key` unchanged on a later update to avoid overwriting a concurrent change.
### Error responses
| Status | Code | Description |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `invalid-payload` | The request failed validation. This covers schema failures and business-logic failures such as editing a structural node on an active journey. |
| 403 | `journey-not-entitled` | Journeys are not enabled for this app. |
| 404 | `journey-not-found` | No journey with that `id` exists for this app. |
| 404 | `journey-node-not-found` | No node with that `node_id` exists in the journey. |
| 409 | `journey-stale` | The supplied `concurrency_key` no longer matches the journey; it changed since it was last fetched. |
| 422 | `journey-archived` | Archived journeys cannot be edited. |
| 429 | | Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying. See [Rate limits](/reference/rate-limits). |
Coded errors use the shape `{ "errors": [{ "code", "title", "meta" }] }`. For validation errors the failing field is in `meta.attribute`. Schema failures on this endpoint are reported against the merged journey, so the offending property is identified in the message by its position in the full graph, such as `#/nodes/1/bogus`.
## OpenAPI
````yaml PATCH /apps/{app_id}/journeys/{id}/nodes/{node_id}
openapi: 3.1.0
info:
title: api.onesignal.com
version: '11.6'
servers:
- url: https://api.onesignal.com
security:
- {}
paths:
/apps/{app_id}/journeys/{id}/nodes/{node_id}:
patch:
summary: Update journey node
description: >-
Apply a partial update to a single node, located by its server-assigned
`id`, using JSON Merge Patch ([RFC
7396](https://datatracker.ietf.org/doc/html/rfc7396)). Send only the
node fields you want to change; the rest of the node and the rest of the
journey graph are left untouched, so in-flight users are preserved.
Prefer this over re-sending the whole `nodes` array through [Update
journey](/reference/update-journey), which replaces the graph wholesale.
Returns the full updated journey.
operationId: update-journey-node
parameters:
- name: app_id
in: path
description: >-
Your OneSignal App ID in UUID v4 format. See [Keys &
IDs](/docs/en/keys-and-ids).
schema:
type: string
default: YOUR_APP_ID
required: true
- name: id
in: path
description: UUID of the journey that owns the node.
required: true
schema:
type: string
default: YOUR_JOURNEY_ID
- name: node_id
in: path
description: >-
Server-assigned UUID of the node to update, from a prior [View
journey](/reference/view-journey) fetch.
required: true
schema:
type: string
default: YOUR_NODE_ID
- name: Authorization
in: header
description: >-
Your App API key with prefix `Key `. See [Keys &
IDs](/docs/en/keys-and-ids).
required: true
schema:
type: string
default: Key YOUR_APP_API_KEY
- name: Content-Type
in: header
required: true
schema:
type: string
default: application/json; charset=utf-8
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: true
description: >-
Node fields to change, merged onto the current node. The node's
`kind` and `id` cannot be changed. Send `null` to clear a
nullable field.
properties:
concurrency_key:
type:
- string
- 'null'
description: >-
Optional optimistic-concurrency token. Pass the
`concurrency_key` from a prior fetch to reject the update
with `409` if the journey changed in the meantime. Omit to
skip the check. It is not merged onto the node.
example:
duration_seconds: 43200
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/JourneyDetail'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/JourneyValidationErrorResponse'
example:
errors:
- code: invalid-payload
title: >-
the property '#/nodes/1/bogus' is not defined and the
schema does not allow additional properties
meta:
attribute: base
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/JourneyCodedErrorResponse'
example:
errors:
- code: journey-not-entitled
title: Journeys are not enabled for this app
meta: {}
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/JourneyCodedErrorResponse'
example:
errors:
- code: journey-node-not-found
title: Node not found
meta: {}
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/JourneyCodedErrorResponse'
example:
errors:
- code: journey-stale
title: Journey has changed since it was last fetched
meta: {}
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/JourneyCodedErrorResponse'
example:
errors:
- code: journey-archived
title: Archived Journeys cannot be edited
meta: {}
'429':
description: '429'
headers:
Retry-After:
description: >-
Number of seconds to wait before retrying the request. Always
emitted on 429 responses.
schema:
type: integer
minimum: 0
components:
schemas:
JourneyDetail:
type: object
description: Full journey representation returned by the detail and create endpoints.
properties:
id:
type: string
description: Journey UUID. Read-only.
app_id:
type: string
description: UUID of the app the journey belongs to. Read-only.
name:
type: string
description: Journey name, up to 300 characters.
description:
type:
- string
- 'null'
description: >-
Journey description, up to 1024 characters. Defaults to an empty
string.
state:
type: string
enum:
- draft
- scheduled
- processing
- active
- archived
description: >-
Journey state. Read-only. New journeys are created as `draft`.
`processing` is a transient state while an activation is in
progress, and `archived` is a journey that has been stopped. Change
it through the `state` field on [Update
journey](/reference/update-journey).
created_at:
type: string
description: ISO 8601 creation time. Read-only.
updated_at:
type: string
description: ISO 8601 last-update time. Read-only.
started_at:
type:
- string
- 'null'
description: >-
ISO 8601 time the journey was activated, or `null`. Read-only. May
stay `null` briefly after you set `state` to `active`: activation is
enqueued for processing, and `started_at` populates once the journey
finishes processing and becomes active.
archived_at:
type:
- string
- 'null'
description: ISO 8601 time the journey was archived, or `null`. Read-only.
created_source:
type:
- string
- 'null'
description: >-
Origin of the journey, for example `public_api` or `dashboard`.
Read-only.
audience:
$ref: '#/components/schemas/JourneyAudience'
early_exit:
$ref: '#/components/schemas/JourneyEarlyExit'
reentry_rules:
$ref: '#/components/schemas/JourneyReentryRules'
schedule:
$ref: '#/components/schemas/JourneySchedule'
nodes:
type: array
items:
$ref: '#/components/schemas/JourneyNode'
description: Ordered list of journey nodes.
concurrency_key:
type: string
description: >-
Opaque optimistic-concurrency token. Read-only. Pass it back on
update to guard against overwriting a concurrent change (`409
journey-stale`). Send it back exactly as read from this response; do
not construct or parse it.
JourneyValidationErrorResponse:
type: object
description: >-
Validation error response. Uses the same `code`/`title`/`meta` shape as
every other error; the failing field and any positional detail travel in
`meta`.
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
description: >-
Stable, kebab-case error identifier. Always `invalid-payload`
for validation failures.
title:
type: string
description: Human-readable message. Wording may change between releases.
meta:
type: object
description: >-
Structured context. Always includes `attribute` (the field, or
`base` for request-level errors); may also include `path`,
`node_id`, or `client_node_id`.
JourneyCodedErrorResponse:
type: object
description: Error response with a stable machine-readable `code`.
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
description: >-
Stable, kebab-case error identifier. Does not change once
shipped.
title:
type: string
description: Human-readable message. Wording may change between releases.
meta:
type: object
description: Optional structured context. Shape varies by error.
JourneyAudience:
oneOf:
- type: object
title: segment
required:
- kind
properties:
kind:
type: string
const: segment
included_segment_ids:
type: array
items:
type: string
description: Segment UUIDs whose users enter the journey.
excluded_segment_ids:
type: array
items:
type: string
description: Segment UUIDs whose users are excluded.
future_additions_only:
type: boolean
description: >-
When true, only users who newly match the segment after
activation enter the journey. Defaults to false.
- type: object
title: event_trigger
required:
- kind
properties:
kind:
type: string
const: event_trigger
name:
type: string
description: Event name that triggers entry, up to 255 characters.
attributes:
$ref: '#/components/schemas/JourneyEventTriggerAttributes'
description: >-
The journey entry audience. Either a segment-based or event-triggered
audience.
JourneyEarlyExit:
type:
- object
- 'null'
description: >-
Conditions that remove a user from the journey before it completes. At
least one rule must be set under `rules`; an early_exit that configures
no rule is rejected. Send `null` to remove early exit entirely, or
`null` for an individual rule to drop just that rule.
properties:
rules:
type: object
properties:
on_segment:
type:
- object
- 'null'
properties:
included_segment_ids:
type: array
items:
type: string
description: Exit when the user enters any of these segments.
when_not_in_audience:
type:
- boolean
- 'null'
description: >-
Exit when the user no longer matches the journey audience.
Defaults to false.
on_session:
type:
- boolean
- 'null'
description: Exit on a new session start. Defaults to false.
on_event:
type:
- object
- 'null'
required:
- name
properties:
name:
type: string
description: Exit when this event occurs. Up to 255 characters.
tag_on_early_exit:
type: object
additionalProperties:
type: string
description: Tag key-value pairs applied when a user exits early.
JourneyReentryRules:
type:
- object
- 'null'
description: >-
Controls whether and how soon a user can re-enter the journey. `null`
means re-entry is not allowed.
properties:
duration_seconds:
type: integer
minimum: 600
description: >-
Minimum seconds before a user can re-enter. Must be at least `600`
(10 minutes).
JourneySchedule:
type:
- object
- 'null'
description: >-
Optional future start and/or stop time. `null` means no scheduled
activation.
properties:
start_at:
type:
- string
- 'null'
description: >-
ISO 8601 start time. Use UTC (`Z` or `+00:00`). Must be at least 5
minutes in the future.
stop_at:
type:
- string
- 'null'
description: >-
ISO 8601 stop time. Use UTC (`Z` or `+00:00`). Must be in the future
and later than `start_at`.
error:
type:
- string
- 'null'
description: Read-only. Present when a scheduling error occurred.
JourneyNode:
oneOf:
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: wait
description: Holds the user for a fixed duration before continuing.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
duration_seconds:
type: integer
description: >-
Seconds to hold the user. Minimum `60`, maximum `31556952` (1
year).
minimum: 60
maximum: 31556952
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: time_window
description: Holds the user until the next configured time window opens.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
relative_to:
type: string
enum:
- schedule_in_timezone
- last_active_time
description: >-
`schedule_in_timezone` uses the configured windows;
`last_active_time` holds relative to the user's last active
time.
windows:
type: array
items:
$ref: '#/components/schemas/JourneyTimeWindow'
description: >-
One or more time windows. A window with no `day_of_week` applies
to every day, and is returned in that same day-agnostic form.
Required when `relative_to` is `schedule_in_timezone`; must be
omitted when it is `last_active_time`, and is absent from
responses for those nodes.
time_zone:
type: string
description: >-
IANA timezone identifier used when the user's timezone is
unavailable.
use_user_time_zone:
type: boolean
description: When true, uses the user's timezone if available.
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
enum:
- send_push
- send_email
- send_sms
description: Sends a message on the given channel using a template.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
template_id:
type: string
description: UUID of the template to send.
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: send_iam
description: Sends an in-app message.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
iam_id:
type: string
description: UUID of the in-app message to send.
user_ttl_seconds:
type: integer
minimum: 1
description: Optional time-to-live for the in-app message, in seconds.
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: send_webhook
description: Sends a webhook.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
webhook_id:
type: string
description: UUID of the webhook to send.
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: tag
description: Assigns key-value tags to the user.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
assignments:
type: object
additionalProperties:
type: string
description: >-
Tag key-value pairs to assign. An empty string value removes the
tag. Keys are limited to 255 characters and values to 1024.
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: split_range
description: >-
Routes users into weighted branches that converge to the next
sibling node.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
randomize_on_entry:
type: boolean
description: >-
When true, assigns each user to a branch at random on entry.
Defaults to false.
branches:
type: array
items:
$ref: '#/components/schemas/JourneyBranch'
description: >-
Weighted branches. Between 2 and 20. Weights must sum to 100.
Order determines display order.
minItems: 2
maxItems: 20
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: yes_no
description: Routes users into a yes or no branch based on a condition.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
branches:
type: array
minItems: 2
maxItems: 2
items:
$ref: '#/components/schemas/JourneyBranch'
description: >-
Exactly two branches. The branch with a `condition` is the "yes"
branch; the branch without one is the "no" branch.
- type: object
required:
- kind
properties:
id:
type: string
description: >-
Server-assigned node UUID. Read-only. Returned on reads; sending
it on create is rejected with a `400` validation error.
kind:
type: string
const: wait_until
description: >-
Holds the user until any branch condition is met, or an optional
expiration timer fires.
client_node_id:
type: string
description: >-
Optional client-assigned identifier, unique within the journey.
Use it to reference this node from elsewhere in the same request
(for example as `client_node_id` on an `on_notification_action`
condition). Persisted and returned on reads.
annotation:
type: string
description: >-
Optional free-text label, up to 255 characters. Stored and
returned as-is with no effect on journey behavior.
branches:
type: array
items:
$ref: '#/components/schemas/JourneyBranch'
description: >-
Condition branches. At least one required, at most 10. Order
determines priority.
expiration:
type:
- object
- 'null'
properties:
duration_seconds:
type: integer
minimum: 60
description: >-
Seconds to wait before the timer fires. Minimum `60`,
maximum `31556952` (1 year).
maximum: 31556952
exits:
type: boolean
description: >-
When true, the user exits the journey when the timer fires;
when false, the user continues to convergence.
description: Optional expiration timer. `null` waits indefinitely.
description: >-
A journey node. The `kind` field selects the shape. Branching nodes
(`split_range`, `yes_no`, `wait_until`) nest their sub-graphs inline via
`branches[].nodes`.
JourneyEventTriggerAttributes:
type: array
description: >-
Event attribute matchers, as a list of condition groups. Send a single
group whose conditions are AND'd together. More than one group is
rejected.
items:
type: array
items:
type: object
required:
- key
- operator
properties:
key:
type: string
description: Event attribute key.
operator:
type: string
enum:
- equal
- not_equal
- less
- less_or_equal
- greater_or_equal
- greater
- is
- is_not
- exists
- not_exists
- before
- after
description: Comparison operator.
value:
type: string
description: >-
Value to compare against. Not required for `exists` and
`not_exists`.
JourneyTimeWindow:
type: object
properties:
start:
allOf:
- $ref: '#/components/schemas/JourneyTimePoint'
description: When the window opens.
end:
allOf:
- $ref: '#/components/schemas/JourneyTimePoint'
description: When the window closes.
day_of_week:
type: integer
minimum: 1
maximum: 7
description: Day of week, 1 = Monday. Omit to apply the window to every day.
description: A wall-clock window. Each window must span at least 15 minutes.
JourneyBranch:
type: object
properties:
id:
type: string
description: Server-assigned branch identifier. Read-only.
condition:
$ref: '#/components/schemas/JourneyCondition'
weight:
type: number
description: >-
Branch weight for `split_range` nodes. Weights across a node's
branches must sum to 100.
nodes:
type: array
items:
$ref: '#/components/schemas/JourneyNode'
description: >-
Nodes run when this branch is taken, before flow converges to the
next sibling node.
JourneyTimePoint:
type: object
properties:
hour:
type: integer
minimum: 0
maximum: 23
description: Hour of day, 0-23.
minute:
type: integer
minimum: 0
maximum: 59
description: Minute of hour, 0-59. Defaults to 0.
JourneyCondition:
oneOf:
- type: object
title: segment_membership
required:
- kind
properties:
kind:
type: string
const: segment_membership
included_segment_ids:
type: array
items:
type: string
description: Segment UUIDs the user must belong to.
excluded_segment_ids:
type: array
items:
type: string
description: Segment UUIDs the user must not belong to.
- type: object
title: on_notification_action
required:
- kind
properties:
kind:
type: string
const: on_notification_action
action:
type: string
enum:
- received
- clicked
- opened
description: >-
The notification action to branch on. Which actions apply
depends on the sending node's channel.
sending_node_id:
type: string
description: >-
`id` of the sending node this action refers to. Returned on
reads; accepted on write.
client_node_id:
type: string
description: >-
Write-only alternative to `sending_node_id`. References the
sending node by its `client_node_id`, which is resolved to that
node's `id`.
- type: object
title: event_trigger
required:
- kind
properties:
kind:
type: string
const: event_trigger
name:
type: string
description: Event name, up to 255 characters.
attributes:
$ref: '#/components/schemas/JourneyEventTriggerAttributes'
entry_event_match_attributes:
type:
- array
- 'null'
items:
type: object
description: >-
Match incoming event properties against the journey's entry
event. Only valid on event-triggered journeys.
description: A branch condition. The `kind` field selects the shape.
````