---
title: "Create Workflow V2"
method: POST
path: "/v1/scenario"
tags: ["Scenario Builder"]
---

# Create Workflow V2

`POST /v1/scenario`

Create a workflows_v2 row with a React Flow graph definition.

## Headers

- `X-API-Key` string, required

## Request body

- CreateWorkflowV2Request — Create a workflow; ``definition`` is a React Flow graph (``nodes``, ``edges``, optional ``viewport``).
  - `name` string, required — Name of the workflow
  - `agent_ids` integer[], nullable — Owning agents (must belong to your organization). Omit or null for org-only workflow.
  - `description` string, nullable — Human-readable description of the workflow
  - `definition` object, required — React Flow graph. Omitted `nodes` / `edges` default to []. Each node must have a non-empty string `id` on the node object (not only inside `data`). Each edge must have a non-empty string `id`, unique across all edges. With no `single` or `options` nodes, the graph is stored as a draft (only multiple-start is rejected). Once there is content, export rules apply (paths, branch_options, etc.).

## Response `200`

Successful Response

- WorkflowV2Response — Single workflows_v2 row.
  - `id` string, required — Workflow ID
  - `organization_id` string, nullable — Owning organization ID (set by middleware on create)
  - `agent_ids` integer[] — Linked agent ids when the workflow is agent-scoped
  - `name` string, required — Name of the workflow
  - `description` string, nullable — Description
  - `definition` object, required — Stored React Flow graph (`start` / `single` / `options` nodes). Nodes and edges use top-level string `id` fields; edge `id` values are unique within the graph.
  - `created_at` string, date-time, required — Creation timestamp
  - `dh_sync_summary` object, nullable — Present on PUT responses when the definition was updated. Keys: updated, created, marked_stale, skipped, errors.
  - `warnings` string[] — Non-blocking lint warnings emitted at save time (e.g. node text referencing an unknown ``{{trait_name}}``). Empty when the definition is clean or no agents are linked.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/getbluejay/apis/bluejay-api.md) · [All operations](https://skmtc.net/getbluejay/apis/bluejay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbluejay/bluejay-api/versions/f48cef80963f/schema)