> ## 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
x-codeSamples:
- lang: typescript
label: Node.js SDK
source: >-
import Onesignal from '@onesignal/node-onesignal';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
// string | Your OneSignal App ID in UUID v4 format.
const appId: string = "YOUR_APP_ID";
// string | UUID of the journey that owns the node.
const journeyId: string = "YOUR_JOURNEY_ID";
// string | Server-assigned UUID of the node to update, from a prior
View journey fetch.
const nodeId: string = "YOUR_NODE_ID";
// UpdateJourneyNodeRequest
const updateJourneyNodeRequest: Onesignal.UpdateJourneyNodeRequest =
{
client_node_id: "client_node_id_example",
annotation: "annotation_example",
duration_seconds: 60,
relative_to: "schedule_in_timezone",
windows: [
{
start: null,
end: null,
day_of_week: 1,
},
],
time_zone: "time_zone_example",
use_user_time_zone: true,
template_id: "template_id_example",
iam_id: "iam_id_example",
user_ttl_seconds: 1,
webhook_id: "webhook_id_example",
assignments: {
"key": "key_example",
},
randomize_on_entry: true,
branches: [
{
id: "id_example",
condition: {
kind: "segment_membership",
included_segment_ids: [
"included_segment_ids_example",
],
excluded_segment_ids: [
"excluded_segment_ids_example",
],
action: "received",
sending_node_id: "sending_node_id_example",
client_node_id: "client_node_id_example",
name: "name_example",
attributes: [
[
{
key: "key_example",
operator: "equal",
value: "value_example",
},
],
],
entry_event_match_attributes: [
{},
],
},
weight: 3.14,
nodes: [
{
id: "id_example",
kind: "wait",
client_node_id: "client_node_id_example",
annotation: "annotation_example",
duration_seconds: 60,
relative_to: "schedule_in_timezone",
windows: [
{
start: null,
end: null,
day_of_week: 1,
},
],
time_zone: "time_zone_example",
use_user_time_zone: true,
template_id: "template_id_example",
iam_id: "iam_id_example",
user_ttl_seconds: 1,
webhook_id: "webhook_id_example",
assignments: {
"key": "key_example",
},
randomize_on_entry: true,
branches: [],
expiration: {
duration_seconds: 60,
exits: true,
},
},
],
},
],
expiration: {
duration_seconds: 60,
exits: true,
},
concurrency_key: "concurrency_key_example",
};
try {
const response = await apiInstance.updateJourneyNode(appId, journeyId, nodeId, updateJourneyNodeRequest);
console.log(response);
} catch (e) {
if (e instanceof Onesignal.ApiException) {
// `e.errorMessages` flattens any error-envelope shape to a `string[]`;
// the raw parsed body remains on `e.body`.
console.error("updateJourneyNode failed: HTTP " + e.code, e.errorMessages);
} else {
throw e;
}
}
- lang: python
label: Python SDK
source: >-
import onesignal
from onesignal.api import default_api
from onesignal.models import *
from pprint import pprint
# See configuration.py for a list of all supported configuration
parameters.
# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token
for authorization, while others require REST_API_KEY.
# We recommend adding both of them in the configuration page so that
you will not need to figure it out yourself.
configuration = onesignal.Configuration(
rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints
organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints
)
# Enter a context with an instance of the API client
with onesignal.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = default_api.DefaultApi(api_client)
app_id = "YOUR_APP_ID" # Your OneSignal App ID in UUID v4 format.
journey_id = "YOUR_JOURNEY_ID" # UUID of the journey that owns the node.
node_id = "YOUR_NODE_ID" # Server-assigned UUID of the node to update, from a prior View journey fetch.
update_journey_node_request = UpdateJourneyNodeRequest(
client_node_id="client_node_id_example",
annotation="annotation_example",
duration_seconds=60,
relative_to="schedule_in_timezone",
windows=[
JourneyTimeWindow(
start=None,
end=None,
day_of_week=1,
),
],
time_zone="time_zone_example",
use_user_time_zone=True,
template_id="template_id_example",
iam_id="iam_id_example",
user_ttl_seconds=1,
webhook_id="webhook_id_example",
assignments={
"key": "key_example",
},
randomize_on_entry=True,
branches=[
JourneyBranch(
id="id_example",
condition=JourneyCondition(
kind="segment_membership",
included_segment_ids=[
"included_segment_ids_example",
],
excluded_segment_ids=[
"excluded_segment_ids_example",
],
action="received",
sending_node_id="sending_node_id_example",
client_node_id="client_node_id_example",
name="name_example",
attributes=JourneyEventTriggerAttributes([
[
JourneyEventAttribute(
key="key_example",
operator="equal",
value="value_example",
),
],
]),
entry_event_match_attributes=[
{},
],
),
weight=3.14,
nodes=[
JourneyNode(
id="id_example",
kind="wait",
client_node_id="client_node_id_example",
annotation="annotation_example",
duration_seconds=60,
relative_to="schedule_in_timezone",
windows=[
JourneyTimeWindow(
start=None,
end=None,
day_of_week=1,
),
],
time_zone="time_zone_example",
use_user_time_zone=True,
template_id="template_id_example",
iam_id="iam_id_example",
user_ttl_seconds=1,
webhook_id="webhook_id_example",
assignments={
"key": "key_example",
},
randomize_on_entry=True,
branches=[],
expiration=JourneyWaitUntilExpiration(
duration_seconds=60,
exits=True,
),
),
],
),
],
expiration=JourneyWaitUntilExpiration(
duration_seconds=60,
exits=True,
),
concurrency_key="concurrency_key_example",
)
try:
# Update journey node
api_response = api_instance.update_journey_node(app_id, journey_id, node_id, update_journey_node_request)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->update_journey_node: %s\n" % e)
print("Status Code: %s" % e.status)
print("Response Body: %s" % e.body)
- lang: php
label: PHP SDK
source: >-
setRestApiKeyToken('YOUR_REST_API_KEY')
->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');
$apiInstance = new onesignal\client\Api\DefaultApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client(),
$config
);
$app_id = 'YOUR_APP_ID'; // string | Your OneSignal App ID in UUID
v4 format.
$journey_id = 'YOUR_JOURNEY_ID'; // string | UUID of the journey
that owns the node.
$node_id = 'YOUR_NODE_ID'; // string | Server-assigned UUID of the
node to update, from a prior View journey fetch.
$update_journey_node_request = new
\onesignal\client\model\UpdateJourneyNodeRequest(); //
\onesignal\client\model\UpdateJourneyNodeRequest
try {
$result = $apiInstance->updateJourneyNode($app_id, $journey_id, $node_id, $update_journey_node_request);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->updateJourneyNode: ', $e->getMessage(), PHP_EOL;
echo 'Status Code: ', $e->getCode(), PHP_EOL;
// getErrorMessages() flattens any error-envelope shape to a string[];
// the raw body remains on getResponseBody().
echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;
echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;
} catch (\Exception $e) {
echo 'Exception when calling DefaultApi->updateJourneyNode: ', $e->getMessage(), PHP_EOL;
}
- lang: go
label: Go SDK
source: |-
package main
import (
"context"
"fmt"
"os"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
appId := "YOUR_APP_ID" // string | Your OneSignal App ID in UUID v4 format.
journeyId := "YOUR_JOURNEY_ID" // string | UUID of the journey that owns the node.
nodeId := "YOUR_NODE_ID" // string | Server-assigned UUID of the node to update, from a prior View journey fetch.
updateJourneyNodeRequest := *onesignal.NewUpdateJourneyNodeRequest() // UpdateJourneyNodeRequest |
configuration := onesignal.NewConfiguration()
apiClient := onesignal.NewAPIClient(configuration)
restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY") // App REST API key required for most endpoints
resp, r, err := apiClient.DefaultApi.UpdateJourneyNode(restAuth, appId, journeyId, nodeId).UpdateJourneyNodeRequest(updateJourneyNodeRequest).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.UpdateJourneyNode``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {
// ErrorMessages() flattens any error-envelope shape to a []string;
// the raw body remains on Body().
fmt.Fprintf(os.Stderr, "Error Messages: %v\n", apiErr.ErrorMessages())
fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body())
}
}
// response from `UpdateJourneyNode`: Journey
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.UpdateJourneyNode`: %v\n", resp)
}
- lang: ruby
label: Ruby SDK
source: >-
require 'onesignal'
# setup authorization
OneSignal.configure do |config|
# Configure Bearer authorization: rest_api_key
config.rest_api_key = 'YOUR_REST_API_KEY'
end
api_instance = OneSignal::DefaultApi.new
app_id = 'YOUR_APP_ID' # String | Your OneSignal App ID in UUID v4
format.
journey_id = 'YOUR_JOURNEY_ID' # String | UUID of the journey that
owns the node.
node_id = 'YOUR_NODE_ID' # String | Server-assigned UUID of the node
to update, from a prior View journey fetch.
update_journey_node_request =
OneSignal::UpdateJourneyNodeRequest.new # UpdateJourneyNodeRequest
|
begin
# Update journey node
result = api_instance.update_journey_node(app_id, journey_id, node_id, update_journey_node_request)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->update_journey_node: #{e}"
puts "Status Code: #{e.code}"
# `e.error_messages` flattens any error-envelope shape to an Array;
# the raw body remains on `e.response_body`.
puts "Error Messages: #{e.error_messages}"
puts "Response Body: #{e.response_body}"
end
- lang: java
label: Java SDK
source: |-
// Import classes:
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.model.*;
import com.onesignal.client.api.DefaultApi;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.onesignal.com");
// Configure HTTP bearer authorization: rest_api_key
HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key");
rest_api_key.setBearerToken("YOUR_REST_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String appId = "YOUR_APP_ID"; // String | Your OneSignal App ID in UUID v4 format.
String journeyId = "YOUR_JOURNEY_ID"; // String | UUID of the journey that owns the node.
String nodeId = "YOUR_NODE_ID"; // String | Server-assigned UUID of the node to update, from a prior View journey fetch.
UpdateJourneyNodeRequest updateJourneyNodeRequest = new UpdateJourneyNodeRequest(); // UpdateJourneyNodeRequest |
try {
Journey result = apiInstance.updateJourneyNode(appId, journeyId, nodeId, updateJourneyNodeRequest);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#updateJourneyNode");
System.err.println("Status code: " + e.getCode());
// getErrorMessages() flattens any error-envelope shape to a List;
// the raw body remains on getResponseBody().
System.err.println("Error messages: " + e.getErrorMessages());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
- lang: csharp
label: C# SDK
source: |-
using System;
using System.Collections.Generic;
using System.Diagnostics;
using OneSignalApi.Api;
using OneSignalApi.Client;
using OneSignalApi.Model;
namespace Example
{
public class UpdateJourneyNodeExample
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.onesignal.com";
// Configure Bearer token for authorization: rest_api_key
config.AccessToken = "YOUR_REST_API_KEY";
var apiInstance = new DefaultApi(config);
var appId = "YOUR_APP_ID"; // string | Your OneSignal App ID in UUID v4 format.
var journeyId = "YOUR_JOURNEY_ID"; // string | UUID of the journey that owns the node.
var nodeId = "YOUR_NODE_ID"; // string | Server-assigned UUID of the node to update, from a prior View journey fetch.
var updateJourneyNodeRequest = new UpdateJourneyNodeRequest(); // UpdateJourneyNodeRequest |
try
{
// Update journey node
Journey result = apiInstance.UpdateJourneyNode(appId, journeyId, nodeId, updateJourneyNodeRequest);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.UpdateJourneyNode: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
// e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;
// the raw body remains on e.ErrorContent.
Debug.Print("Error Messages: " + string.Join(", ", e.ErrorMessages));
Debug.Print("Response Body: " + e.ErrorContent);
Debug.Print(e.StackTrace);
}
}
}
}
- lang: rust
label: Rust SDK
source: |-
use onesignal_rust_api::apis::configuration::Configuration;
use onesignal_rust_api::apis::default_api;
use onesignal_rust_api::models;
#[tokio::main]
async fn main() {
let mut configuration = Configuration::new();
configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
// Realistic values are pulled from the spec's `example:` fields where present.
let app_id: &str = "YOUR_APP_ID";
let journey_id: &str = "YOUR_JOURNEY_ID";
let node_id: &str = "YOUR_NODE_ID";
let update_journey_node_request: models::UpdateJourneyNodeRequest = todo!();
match default_api::update_journey_node(&configuration, app_id, journey_id, node_id, update_journey_node_request).await {
Ok(resp) => println!("{:?}", resp),
Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {
// `e.error_messages()` flattens any error-envelope shape to a Vec;
// the raw response remains on the ResponseError variant.
eprintln!("update_journey_node failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("update_journey_node failed: {:?}", e),
}
}
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.
````