Replace a workflow's step graph
Replaces the whole graph in one transaction, because a graph is only meaningful as nodes PLUS the edges between them — an edit that could apply half of it would leave steps pointing at steps that no longer exist.
A step whose id you send is kept and updated in place; a fresh uuid creates one; an id you omit deletes that step and its run history. Exactly one step must be a TRIGGER, every transition must name steps present in the same document, and a step may not point at itself.
Refused with 409 while the workflow has running executions: those runs are standing on the steps being replaced. Pause the workflow (POST /api/v1/workflows/{id}/pause) first.
The response of GET /api/v1/workflows/{id}/graph is accepted verbatim by PUT on the same path: read a graph, change a step, send it back. Step and transition ids are yours to choose on a write, which is what makes that round trip a no-op rather than a rebuild.
Requires the workflows:write scope — Create, edit, enable, and delete your automation workflows.
API key authentication. Use a sk_* (FULL) or pk_* (SENDING_ONLY) key as the bearer token. Public keys (pk_*) are restricted to the email-send endpoints and the self-serve list subscribe/unsubscribe pair; every other endpoint — event tracking included — answers 403 for them. In scope terms (used by /api/v1/* operations): FULL keys hold every scope; SENDING_ONLY keys hold only emails:send.
In: header
Path Parameters
Workflow id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Body for PUT /api/v1/workflows/{id}/graph. Replaces the whole graph: a step whose id you send is kept and updated, a fresh id is created, and a step you omit is deleted along with its run history. Refused with 409 while the workflow has running executions, because those runs are standing on the steps being replaced.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X PUT "https://example.com/api/v1/workflows/497f6eca-6276-4993-bfeb-53cbbbba6f08/graph" \ -H "Content-Type: application/json" \ -d '{ "steps": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "position": { "x": 0, "y": 0, "property1": "string", "property2": "string" }, "type": "TRIGGER", "config": { "property1": "string", "property2": "string" } } ], "transitions": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "from_step_id": "e4c3aeab-3fd1-4e4e-9277-1338b28978a8", "to_step_id": "b9ed3588-525d-4e92-bfb0-711a014dbce6", "condition": "string", "priority": 0 } ] }'{
"workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe",
"version": 0,
"steps": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"position": {
"x": 0,
"y": 0,
"property1": "string",
"property2": "string"
},
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"type": "TRIGGER",
"config": {
"property1": "string",
"property2": "string"
}
}
],
"transitions": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"from_step_id": "e4c3aeab-3fd1-4e4e-9277-1338b28978a8",
"to_step_id": "b9ed3588-525d-4e92-bfb0-711a014dbce6",
"condition": "string",
"priority": 0
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}