Automation scenarios tools

search_scenarios: List the automation scenarios in a project, or fetch one by ID.
list_scenario_nodes: Get a lightweight node skeleton for a scenario.
get_scenario_node: Get the full configuration of a single node in a scenario.
create_scenario: Create a new scenario as a draft.
update_scenario: Replace the full definition of a draft or inactive scenario.
delete_scenario: Permanently delete a draft or inactive scenario.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Bloomreach Engagement dashboard, actions your users or agents take with these tools can have a substantial impact on your campaigns, automations, and customer communications. There is no automatic rollback and activity logging is limited, so review every change and confirm the target before applying it.

search_scenarios

Searches the scenarios (automation flow campaigns) in a project, or fetches one by ID. Scenarios are multi-step flows with triggers, conditions, waits, and actions. Omit scenario_id to list all scenarios as summary records: name, status, tags, archived flag, and initiative assignment. The node graph is excluded from the list — pass scenario_id, or use the lighter-weight list_scenario_nodes, to explore it.

Pass scenario_id to fetch the complete scenario definition, including the trigger, every node in the flow graph (waits, conditions, actions, A/B splits), the global customer filter, and metadata. Email and SMS design payloads are stripped from nodes by default to keep responses manageable. Set include_node_designs to true to include them, though design blobs can be 70 KB or more per node.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str \| null`	No	The scenario ID. Omit to list all; provide to fetch one.
`include_node_designs`	`bool`	No	When fetching a single scenario, include the full email or SMS design payload in action nodes. Ignored when `scenario_id` is omitted. Defaults to false.

Response parameters

The tool returns a ScenariosResponse when scenario_id is omitted, or a ScenarioResponse when it's provided.

The ScenariosResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[ScenarioSummary]`	The scenario summaries.
`error`	`str \| null`	Error message if the request failed.

The ScenarioSummary object has the following fields:

Field	Type	Description
`id`	`str`	The scenario's unique ID.
`name`	`str`	The scenario's display name.
`status`	`str`	One of `draft`, `active`, `inactive`, `finishing`, or `finished`.
`archived`	`bool`	Whether the scenario has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this scenario belongs to, if any.
`is_global_object`	`bool \| null`	Whether the scenario is a global, shared object.
`created`	`any \| null`	Unix timestamp of when the scenario was created.
`created_by_display_name`	`str \| null`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str \| null`	Display name of the last editor.

When scenario_id is provided, the tool returns a ScenarioResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Scenario \| null`	The full scenario definition.
`error`	`str \| null`	Error message if the request failed.

The Scenario object adds the following fields on top of the summary record:

Field	Type	Description
`trigger`	`any \| null`	The entry trigger: an event, a schedule, or an API call.
`nodes`	`list[any]`	The scenario node graph. Each node is one step in the flow — a wait, an action, a condition, an A/B split, and so on.
`customer_filter`	`any \| null`	The global filter that decides which customers can enter the scenario.
`max_customers`	`int \| null`	The maximum number of customers allowed in the scenario at one time.

list_scenario_nodes

Returns a lightweight skeleton of a scenario's node graph: just the node IDs, types, names, and the connections (edges) between them. Use this to explore a scenario's structure before pulling individual nodes with get_scenario_node.

The scenario is fetched once and cached for 60 seconds, so back-to-back calls to list_scenario_nodes and get_scenario_node on the same scenario share a single underlying request.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios`.

Response parameters

The tool returns a ScenarioNodesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`scenario_id`	`str`	The scenario's ID.
`scenario_name`	`str`	The scenario's display name.
`nodes`	`list[ScenarioNodeSummary]`	A lightweight list of nodes: ID, type, and name only.
`connections`	`list[any]`	The graph edges. Each entry has a `source` (`node_id` plus `connector_index`) and a `destination`. On branching nodes (`condition` and `ab-split`), the `connector_index` identifies which output branch: 0 is the yes or first variant, 1 is the no or second variant, and so on.
`trigger`	`any`	The entry trigger configuration for the scenario.
`error`	`str \| null`	Error message if the request failed.

The ScenarioNodeSummary object has the following fields:

Field	Type	Description
`id`	`int`	The numeric node ID, unique within the scenario.
`type`	`str`	The node type, for example `send-email-action`, `condition`, `wait-action`, or `ab-split`.
`name`	`str \| null`	An optional display label set by the scenario author.
`incoming_connections`	`list[any]`	The edges arriving at this node from parent nodes. Empty for entry-point trigger nodes.
`outgoing_connections`	`list[any]`	The edges leaving this node toward child nodes. On branching nodes, `connector_index` identifies which branch.

get_scenario_node

Returns the full configuration for a single node in a scenario, along with the incoming and outgoing edges. The scenario is fetched once and cached for 60 seconds, so this is efficient to call repeatedly on the same scenario.

The design payload on action nodes (email or MMS templates) is omitted by default because a single design can run to 70 KB or more. Set include_design to true if you need the template content.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios`.
`node_id`	`int`	Yes	The numeric node ID. Use `list_scenario_nodes` to discover node IDs.
`include_design`	`bool`	No	If true, include the `design` field on action nodes. Defaults to false.

Response parameters

The tool returns a ScenarioNodeResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`scenario_id`	`str`	The scenario this node belongs to.
`node`	`any \| null`	The full node configuration. The shape varies by node type.
`incoming_connections`	`list[any]`	The edges arriving at this node from parent nodes. Empty for entry-point nodes.
`outgoing_connections`	`list[any]`	The edges leaving this node toward child nodes. On branching nodes, `connector_index` identifies which branch. Empty for terminal nodes.
`error`	`str \| null`	Error message if the request failed or the node was not found.

create_scenario

Creates a new scenario (automation flow). The scenario is always created as a draft — it does not run until it is activated in the Bloomreach Engagement UI. On success, the tool returns the ID of the new scenario.

The payload requires a name, a nodes list with at minimum one trigger node, a connections list of edges between nodes (empty for a trigger-only scenario), and a last_node_id set to the highest node ID present in nodes. A trigger node's type can be on-event-trigger, on-api-trigger, on-date-attribute-trigger, repeated-trigger, planned-trigger, or now-trigger, and each type has its own required sub-fields.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`payload`	`dict`	Yes	The scenario definition. Requires `name`, `nodes`, `connections`, and `last_node_id`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the newly created scenario.
`error`	`str \| null`	Error or validation detail if the operation failed.

update_scenario

Replaces the full definition of an existing scenario with the payload you provide (PUT semantics), so pass the complete scenario, not just the fields you want to change. The typical workflow is to fetch the current definition with search_scenarios, modify the fields you need, then pass the whole modified object here. The scenario must be in draft or inactive status — running scenarios cannot be modified, and status transitions such as activate and stop must be done through the Engagement UI.

Keep existing node IDs intact, since the backend matches nodes by ID and treats a changed ID as deleting the old node and creating a new one. Set last_node_id to the highest node ID in the nodes array, and update it whenever you add new nodes. Find scenario IDs with search_scenarios.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios` or `create_scenario`.
`payload`	`dict`	Yes	The full updated scenario definition, in the same shape as create.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the updated scenario.
`error`	`str \| null`	Error or validation detail if the operation failed.

delete_scenario

Permanently deletes a scenario. The scenario must be in draft or inactive status — running scenarios cannot be deleted. This action is irreversible: the scenario and all its node configuration are removed, and there is no undo through this tool, so verify the target before you run it.

Find scenario IDs with search_scenarios.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	Not present for deletes.
`error`	`str \| null`	Error detail if the operation failed.