Update flow definition
curl --request PUT \
--url https://flows.super.ai/api/flows/{flow_id}/definition \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"definition": {
"flow": {
"author_uuid": "",
"created_at": ""
},
"flow_configs": [
{
"config": {
"groups": [],
"notes": [],
"tasks": [
{
"is_schedulable_executor": false,
"name": "e264bc8d-d6d3-4bef-a18e-a27ad491cd26",
"parameters": {},
"task_executor_name": "receive_file",
"task_title": "Receive File",
"visual_properties": {
"collapsed": false,
"position": {
"x": 584.5,
"y": 359.5
},
"zIndex": 2
}
},
{
"is_schedulable_executor": false,
"name": "6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6",
"parameters": {
"document_url": "{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}",
"fields": [
{
"columns": [],
"data_type": "int",
"id": "InvoiceID",
"instructions": "",
"title": "Invoice ID"
}
],
"worker": "gpt-4.1"
},
"task_executor_name": "doc_to_structured",
"task_title": "Doc To Structured",
"visual_properties": {
"collapsed": false,
"position": {
"x": 1170,
"y": 360
},
"zIndex": 2
}
}
]
},
"meta": {
"description": "Extract data from invoices",
"name": "Invoice Processing"
}
}
]
},
"expected_revision": "<string>"
}
'import requests
url = "https://flows.super.ai/api/flows/{flow_id}/definition"
payload = {
"definition": {
"flow": {
"author_uuid": "",
"created_at": ""
},
"flow_configs": [
{
"config": {
"groups": [],
"notes": [],
"tasks": [
{
"is_schedulable_executor": False,
"name": "e264bc8d-d6d3-4bef-a18e-a27ad491cd26",
"parameters": {},
"task_executor_name": "receive_file",
"task_title": "Receive File",
"visual_properties": {
"collapsed": False,
"position": {
"x": 584.5,
"y": 359.5
},
"zIndex": 2
}
},
{
"is_schedulable_executor": False,
"name": "6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6",
"parameters": {
"document_url": "{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}",
"fields": [
{
"columns": [],
"data_type": "int",
"id": "InvoiceID",
"instructions": "",
"title": "Invoice ID"
}
],
"worker": "gpt-4.1"
},
"task_executor_name": "doc_to_structured",
"task_title": "Doc To Structured",
"visual_properties": {
"collapsed": False,
"position": {
"x": 1170,
"y": 360
},
"zIndex": 2
}
}
]
},
"meta": {
"description": "Extract data from invoices",
"name": "Invoice Processing"
}
}
]
},
"expected_revision": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
definition: {
flow: {author_uuid: '', created_at: ''},
flow_configs: [
{
config: {
groups: [],
notes: [],
tasks: [
{
is_schedulable_executor: false,
name: 'e264bc8d-d6d3-4bef-a18e-a27ad491cd26',
parameters: {},
task_executor_name: 'receive_file',
task_title: 'Receive File',
visual_properties: {collapsed: false, position: {x: 584.5, y: 359.5}, zIndex: 2}
},
{
is_schedulable_executor: false,
name: '6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6',
parameters: {
document_url: '{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}',
fields: [
{
columns: [],
data_type: 'int',
id: 'InvoiceID',
instructions: '',
title: 'Invoice ID'
}
],
worker: 'gpt-4.1'
},
task_executor_name: 'doc_to_structured',
task_title: 'Doc To Structured',
visual_properties: {collapsed: false, position: {x: 1170, y: 360}, zIndex: 2}
}
]
},
meta: {description: 'Extract data from invoices', name: 'Invoice Processing'}
}
]
},
expected_revision: '<string>'
})
};
fetch('https://flows.super.ai/api/flows/{flow_id}/definition', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://flows.super.ai/api/flows/{flow_id}/definition",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'definition' => [
'flow' => [
'author_uuid' => '',
'created_at' => ''
],
'flow_configs' => [
[
'config' => [
'groups' => [
],
'notes' => [
],
'tasks' => [
[
'is_schedulable_executor' => false,
'name' => 'e264bc8d-d6d3-4bef-a18e-a27ad491cd26',
'parameters' => [
],
'task_executor_name' => 'receive_file',
'task_title' => 'Receive File',
'visual_properties' => [
'collapsed' => false,
'position' => [
'x' => 584.5,
'y' => 359.5
],
'zIndex' => 2
]
],
[
'is_schedulable_executor' => false,
'name' => '6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6',
'parameters' => [
'document_url' => '{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}',
'fields' => [
[
'columns' => [
],
'data_type' => 'int',
'id' => 'InvoiceID',
'instructions' => '',
'title' => 'Invoice ID'
]
],
'worker' => 'gpt-4.1'
],
'task_executor_name' => 'doc_to_structured',
'task_title' => 'Doc To Structured',
'visual_properties' => [
'collapsed' => false,
'position' => [
'x' => 1170,
'y' => 360
],
'zIndex' => 2
]
]
]
],
'meta' => [
'description' => 'Extract data from invoices',
'name' => 'Invoice Processing'
]
]
]
],
'expected_revision' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://flows.super.ai/api/flows/{flow_id}/definition"
payload := strings.NewReader("{\n \"definition\": {\n \"flow\": {\n \"author_uuid\": \"\",\n \"created_at\": \"\"\n },\n \"flow_configs\": [\n {\n \"config\": {\n \"groups\": [],\n \"notes\": [],\n \"tasks\": [\n {\n \"is_schedulable_executor\": false,\n \"name\": \"e264bc8d-d6d3-4bef-a18e-a27ad491cd26\",\n \"parameters\": {},\n \"task_executor_name\": \"receive_file\",\n \"task_title\": \"Receive File\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 584.5,\n \"y\": 359.5\n },\n \"zIndex\": 2\n }\n },\n {\n \"is_schedulable_executor\": false,\n \"name\": \"6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6\",\n \"parameters\": {\n \"document_url\": \"{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}\",\n \"fields\": [\n {\n \"columns\": [],\n \"data_type\": \"int\",\n \"id\": \"InvoiceID\",\n \"instructions\": \"\",\n \"title\": \"Invoice ID\"\n }\n ],\n \"worker\": \"gpt-4.1\"\n },\n \"task_executor_name\": \"doc_to_structured\",\n \"task_title\": \"Doc To Structured\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 1170,\n \"y\": 360\n },\n \"zIndex\": 2\n }\n }\n ]\n },\n \"meta\": {\n \"description\": \"Extract data from invoices\",\n \"name\": \"Invoice Processing\"\n }\n }\n ]\n },\n \"expected_revision\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://flows.super.ai/api/flows/{flow_id}/definition")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"definition\": {\n \"flow\": {\n \"author_uuid\": \"\",\n \"created_at\": \"\"\n },\n \"flow_configs\": [\n {\n \"config\": {\n \"groups\": [],\n \"notes\": [],\n \"tasks\": [\n {\n \"is_schedulable_executor\": false,\n \"name\": \"e264bc8d-d6d3-4bef-a18e-a27ad491cd26\",\n \"parameters\": {},\n \"task_executor_name\": \"receive_file\",\n \"task_title\": \"Receive File\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 584.5,\n \"y\": 359.5\n },\n \"zIndex\": 2\n }\n },\n {\n \"is_schedulable_executor\": false,\n \"name\": \"6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6\",\n \"parameters\": {\n \"document_url\": \"{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}\",\n \"fields\": [\n {\n \"columns\": [],\n \"data_type\": \"int\",\n \"id\": \"InvoiceID\",\n \"instructions\": \"\",\n \"title\": \"Invoice ID\"\n }\n ],\n \"worker\": \"gpt-4.1\"\n },\n \"task_executor_name\": \"doc_to_structured\",\n \"task_title\": \"Doc To Structured\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 1170,\n \"y\": 360\n },\n \"zIndex\": 2\n }\n }\n ]\n },\n \"meta\": {\n \"description\": \"Extract data from invoices\",\n \"name\": \"Invoice Processing\"\n }\n }\n ]\n },\n \"expected_revision\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://flows.super.ai/api/flows/{flow_id}/definition")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"definition\": {\n \"flow\": {\n \"author_uuid\": \"\",\n \"created_at\": \"\"\n },\n \"flow_configs\": [\n {\n \"config\": {\n \"groups\": [],\n \"notes\": [],\n \"tasks\": [\n {\n \"is_schedulable_executor\": false,\n \"name\": \"e264bc8d-d6d3-4bef-a18e-a27ad491cd26\",\n \"parameters\": {},\n \"task_executor_name\": \"receive_file\",\n \"task_title\": \"Receive File\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 584.5,\n \"y\": 359.5\n },\n \"zIndex\": 2\n }\n },\n {\n \"is_schedulable_executor\": false,\n \"name\": \"6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6\",\n \"parameters\": {\n \"document_url\": \"{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}\",\n \"fields\": [\n {\n \"columns\": [],\n \"data_type\": \"int\",\n \"id\": \"InvoiceID\",\n \"instructions\": \"\",\n \"title\": \"Invoice ID\"\n }\n ],\n \"worker\": \"gpt-4.1\"\n },\n \"task_executor_name\": \"doc_to_structured\",\n \"task_title\": \"Doc To Structured\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 1170,\n \"y\": 360\n },\n \"zIndex\": 2\n }\n }\n ]\n },\n \"meta\": {\n \"description\": \"Extract data from invoices\",\n \"name\": \"Invoice Processing\"\n }\n }\n ]\n },\n \"expected_revision\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2023-11-07T05:31:56Z",
"definition": {},
"display_name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"is_latest": true,
"modified_by": "<string>",
"organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"revision": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"version": 2,
"awaiting_hitl_executions_count": 123,
"awaiting_input_executions_count": 123,
"deleted": false,
"description": "<string>",
"error_executions_count": 123,
"flow_executions_count": 0,
"is_hidden": false,
"last_execution_activity_at": "2023-11-07T05:31:56Z",
"latest_version_executions_count": 123,
"settings": {
"appearance": {
"color": "<string>",
"icon": "<string>",
"text": "<string>"
},
"on_task_error": "continue",
"reexecute_on_update": false,
"review_view_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"ttl": {}
},
"tags": [
"<string>"
],
"task_names": [
"<string>"
],
"validation_errors": [
{
"input": "<unknown>",
"loc": [
123
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"url": "<string>"
}
]
}flows
Update flow definition
Update the complete definition of a flow.
Replaces the entire flow definition with a new one. This operation is only allowed for flows in ‘draft’ status. Creates a new version of the flow.
Restrictions
- Only flows with status ‘draft’ can be updated
- Published flows cannot be modified
- A new version is created with each update
Validation
- New definition is validated before applying
- If validation fails, the original definition remains unchanged
- Use
include_validation_errors=trueto see validation details
Concurrent writers
- Send
expected_revision(therevisionof the flow you read) so a save never overwrites a change made since, for example by an agent: a stale value returns 409revision_conflictand saves nothing - Without it the save is last-writer-wins
PUT
/
api
/
flows
/
{flow_id}
/
definition
Update flow definition
curl --request PUT \
--url https://flows.super.ai/api/flows/{flow_id}/definition \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"definition": {
"flow": {
"author_uuid": "",
"created_at": ""
},
"flow_configs": [
{
"config": {
"groups": [],
"notes": [],
"tasks": [
{
"is_schedulable_executor": false,
"name": "e264bc8d-d6d3-4bef-a18e-a27ad491cd26",
"parameters": {},
"task_executor_name": "receive_file",
"task_title": "Receive File",
"visual_properties": {
"collapsed": false,
"position": {
"x": 584.5,
"y": 359.5
},
"zIndex": 2
}
},
{
"is_schedulable_executor": false,
"name": "6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6",
"parameters": {
"document_url": "{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}",
"fields": [
{
"columns": [],
"data_type": "int",
"id": "InvoiceID",
"instructions": "",
"title": "Invoice ID"
}
],
"worker": "gpt-4.1"
},
"task_executor_name": "doc_to_structured",
"task_title": "Doc To Structured",
"visual_properties": {
"collapsed": false,
"position": {
"x": 1170,
"y": 360
},
"zIndex": 2
}
}
]
},
"meta": {
"description": "Extract data from invoices",
"name": "Invoice Processing"
}
}
]
},
"expected_revision": "<string>"
}
'import requests
url = "https://flows.super.ai/api/flows/{flow_id}/definition"
payload = {
"definition": {
"flow": {
"author_uuid": "",
"created_at": ""
},
"flow_configs": [
{
"config": {
"groups": [],
"notes": [],
"tasks": [
{
"is_schedulable_executor": False,
"name": "e264bc8d-d6d3-4bef-a18e-a27ad491cd26",
"parameters": {},
"task_executor_name": "receive_file",
"task_title": "Receive File",
"visual_properties": {
"collapsed": False,
"position": {
"x": 584.5,
"y": 359.5
},
"zIndex": 2
}
},
{
"is_schedulable_executor": False,
"name": "6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6",
"parameters": {
"document_url": "{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}",
"fields": [
{
"columns": [],
"data_type": "int",
"id": "InvoiceID",
"instructions": "",
"title": "Invoice ID"
}
],
"worker": "gpt-4.1"
},
"task_executor_name": "doc_to_structured",
"task_title": "Doc To Structured",
"visual_properties": {
"collapsed": False,
"position": {
"x": 1170,
"y": 360
},
"zIndex": 2
}
}
]
},
"meta": {
"description": "Extract data from invoices",
"name": "Invoice Processing"
}
}
]
},
"expected_revision": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
definition: {
flow: {author_uuid: '', created_at: ''},
flow_configs: [
{
config: {
groups: [],
notes: [],
tasks: [
{
is_schedulable_executor: false,
name: 'e264bc8d-d6d3-4bef-a18e-a27ad491cd26',
parameters: {},
task_executor_name: 'receive_file',
task_title: 'Receive File',
visual_properties: {collapsed: false, position: {x: 584.5, y: 359.5}, zIndex: 2}
},
{
is_schedulable_executor: false,
name: '6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6',
parameters: {
document_url: '{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}',
fields: [
{
columns: [],
data_type: 'int',
id: 'InvoiceID',
instructions: '',
title: 'Invoice ID'
}
],
worker: 'gpt-4.1'
},
task_executor_name: 'doc_to_structured',
task_title: 'Doc To Structured',
visual_properties: {collapsed: false, position: {x: 1170, y: 360}, zIndex: 2}
}
]
},
meta: {description: 'Extract data from invoices', name: 'Invoice Processing'}
}
]
},
expected_revision: '<string>'
})
};
fetch('https://flows.super.ai/api/flows/{flow_id}/definition', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://flows.super.ai/api/flows/{flow_id}/definition",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'definition' => [
'flow' => [
'author_uuid' => '',
'created_at' => ''
],
'flow_configs' => [
[
'config' => [
'groups' => [
],
'notes' => [
],
'tasks' => [
[
'is_schedulable_executor' => false,
'name' => 'e264bc8d-d6d3-4bef-a18e-a27ad491cd26',
'parameters' => [
],
'task_executor_name' => 'receive_file',
'task_title' => 'Receive File',
'visual_properties' => [
'collapsed' => false,
'position' => [
'x' => 584.5,
'y' => 359.5
],
'zIndex' => 2
]
],
[
'is_schedulable_executor' => false,
'name' => '6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6',
'parameters' => [
'document_url' => '{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}',
'fields' => [
[
'columns' => [
],
'data_type' => 'int',
'id' => 'InvoiceID',
'instructions' => '',
'title' => 'Invoice ID'
]
],
'worker' => 'gpt-4.1'
],
'task_executor_name' => 'doc_to_structured',
'task_title' => 'Doc To Structured',
'visual_properties' => [
'collapsed' => false,
'position' => [
'x' => 1170,
'y' => 360
],
'zIndex' => 2
]
]
]
],
'meta' => [
'description' => 'Extract data from invoices',
'name' => 'Invoice Processing'
]
]
]
],
'expected_revision' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://flows.super.ai/api/flows/{flow_id}/definition"
payload := strings.NewReader("{\n \"definition\": {\n \"flow\": {\n \"author_uuid\": \"\",\n \"created_at\": \"\"\n },\n \"flow_configs\": [\n {\n \"config\": {\n \"groups\": [],\n \"notes\": [],\n \"tasks\": [\n {\n \"is_schedulable_executor\": false,\n \"name\": \"e264bc8d-d6d3-4bef-a18e-a27ad491cd26\",\n \"parameters\": {},\n \"task_executor_name\": \"receive_file\",\n \"task_title\": \"Receive File\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 584.5,\n \"y\": 359.5\n },\n \"zIndex\": 2\n }\n },\n {\n \"is_schedulable_executor\": false,\n \"name\": \"6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6\",\n \"parameters\": {\n \"document_url\": \"{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}\",\n \"fields\": [\n {\n \"columns\": [],\n \"data_type\": \"int\",\n \"id\": \"InvoiceID\",\n \"instructions\": \"\",\n \"title\": \"Invoice ID\"\n }\n ],\n \"worker\": \"gpt-4.1\"\n },\n \"task_executor_name\": \"doc_to_structured\",\n \"task_title\": \"Doc To Structured\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 1170,\n \"y\": 360\n },\n \"zIndex\": 2\n }\n }\n ]\n },\n \"meta\": {\n \"description\": \"Extract data from invoices\",\n \"name\": \"Invoice Processing\"\n }\n }\n ]\n },\n \"expected_revision\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://flows.super.ai/api/flows/{flow_id}/definition")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"definition\": {\n \"flow\": {\n \"author_uuid\": \"\",\n \"created_at\": \"\"\n },\n \"flow_configs\": [\n {\n \"config\": {\n \"groups\": [],\n \"notes\": [],\n \"tasks\": [\n {\n \"is_schedulable_executor\": false,\n \"name\": \"e264bc8d-d6d3-4bef-a18e-a27ad491cd26\",\n \"parameters\": {},\n \"task_executor_name\": \"receive_file\",\n \"task_title\": \"Receive File\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 584.5,\n \"y\": 359.5\n },\n \"zIndex\": 2\n }\n },\n {\n \"is_schedulable_executor\": false,\n \"name\": \"6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6\",\n \"parameters\": {\n \"document_url\": \"{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}\",\n \"fields\": [\n {\n \"columns\": [],\n \"data_type\": \"int\",\n \"id\": \"InvoiceID\",\n \"instructions\": \"\",\n \"title\": \"Invoice ID\"\n }\n ],\n \"worker\": \"gpt-4.1\"\n },\n \"task_executor_name\": \"doc_to_structured\",\n \"task_title\": \"Doc To Structured\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 1170,\n \"y\": 360\n },\n \"zIndex\": 2\n }\n }\n ]\n },\n \"meta\": {\n \"description\": \"Extract data from invoices\",\n \"name\": \"Invoice Processing\"\n }\n }\n ]\n },\n \"expected_revision\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://flows.super.ai/api/flows/{flow_id}/definition")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"definition\": {\n \"flow\": {\n \"author_uuid\": \"\",\n \"created_at\": \"\"\n },\n \"flow_configs\": [\n {\n \"config\": {\n \"groups\": [],\n \"notes\": [],\n \"tasks\": [\n {\n \"is_schedulable_executor\": false,\n \"name\": \"e264bc8d-d6d3-4bef-a18e-a27ad491cd26\",\n \"parameters\": {},\n \"task_executor_name\": \"receive_file\",\n \"task_title\": \"Receive File\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 584.5,\n \"y\": 359.5\n },\n \"zIndex\": 2\n }\n },\n {\n \"is_schedulable_executor\": false,\n \"name\": \"6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6\",\n \"parameters\": {\n \"document_url\": \"{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}\",\n \"fields\": [\n {\n \"columns\": [],\n \"data_type\": \"int\",\n \"id\": \"InvoiceID\",\n \"instructions\": \"\",\n \"title\": \"Invoice ID\"\n }\n ],\n \"worker\": \"gpt-4.1\"\n },\n \"task_executor_name\": \"doc_to_structured\",\n \"task_title\": \"Doc To Structured\",\n \"visual_properties\": {\n \"collapsed\": false,\n \"position\": {\n \"x\": 1170,\n \"y\": 360\n },\n \"zIndex\": 2\n }\n }\n ]\n },\n \"meta\": {\n \"description\": \"Extract data from invoices\",\n \"name\": \"Invoice Processing\"\n }\n }\n ]\n },\n \"expected_revision\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2023-11-07T05:31:56Z",
"definition": {},
"display_name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"is_latest": true,
"modified_by": "<string>",
"organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"revision": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"version": 2,
"awaiting_hitl_executions_count": 123,
"awaiting_input_executions_count": 123,
"deleted": false,
"description": "<string>",
"error_executions_count": 123,
"flow_executions_count": 0,
"is_hidden": false,
"last_execution_activity_at": "2023-11-07T05:31:56Z",
"latest_version_executions_count": 123,
"settings": {
"appearance": {
"color": "<string>",
"icon": "<string>",
"text": "<string>"
},
"on_task_error": "continue",
"reexecute_on_update": false,
"review_view_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"ttl": {}
},
"tags": [
"<string>"
],
"task_names": [
"<string>"
],
"validation_errors": [
{
"input": "<unknown>",
"loc": [
123
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"url": "<string>"
}
]
}Authorizations
BearerAuthAPIKeyAuth
JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN
Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Path Parameters
Query Parameters
Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.
Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.
Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.
Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections.
Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building.
Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.
Body
application/json
Model for flow definition update request.
Flow definition in DSL format. The definition contains a 'flow' metadata object and a 'flow_configs' array with task configurations. Each task has a unique 'name' (UUID), 'task_executor_name' (the task type), 'task_title' (display name), 'parameters' (executor-specific config), and optional 'visual_properties' for UI layout. Tasks reference upstream outputs using '{{task_name.output_field}}' template syntax in their parameters to define dependencies.
Example:
{
"flow": { "author_uuid": "", "created_at": "" },
"flow_configs": [
{
"config": {
"groups": [],
"notes": [],
"tasks": [
{
"is_schedulable_executor": false,
"name": "e264bc8d-d6d3-4bef-a18e-a27ad491cd26",
"parameters": {},
"task_executor_name": "receive_file",
"task_title": "Receive File",
"visual_properties": {
"collapsed": false,
"position": { "x": 584.5, "y": 359.5 },
"zIndex": 2
}
},
{
"is_schedulable_executor": false,
"name": "6ef3e60a-94e7-48b0-adbf-80d3ef81c3a6",
"parameters": {
"document_url": "{{e264bc8d-d6d3-4bef-a18e-a27ad491cd26.document_url}}",
"fields": [
{
"columns": [],
"data_type": "int",
"id": "InvoiceID",
"instructions": "",
"title": "Invoice ID"
}
],
"worker": "gpt-4.1"
},
"task_executor_name": "doc_to_structured",
"task_title": "Doc To Structured",
"visual_properties": {
"collapsed": false,
"position": { "x": 1170, "y": 360 },
"zIndex": 2
}
}
]
},
"meta": {
"description": "Extract data from invoices",
"name": "Invoice Processing"
}
}
]
}
Optional. The revision of the flow this write is based on, from the FlowResponse you last read or saved. When set, the write applies only if the latest version is still at that revision, checked under the flow lock; otherwise nothing is saved and the response is 409 with code revision_conflict and details.current_revision. Reload the flow, re-apply your change and retry. When omitted, the write applies on top of whatever is latest (last writer wins).
Response
Flow definition successfully updated
Response model for a flow object.
Represents a complete flow definition with metadata, execution statistics, and optional computed fields. Use query parameters to include additional fields that require extra processing.
Expansion Parameters
Control which computed fields are included using these query parameters:
include_ordered_task_names: Addstask_namesfield with topological sortinclude_validation_errors: Addsvalidation_errorsfield if flow is invalidinclude_dynamic_data: Enriches each task indefinitionwith runtime config optionsinclude_output_schemas: Enriches each task indefinitionwith JSON schema
Performance Considerations
Each expansion parameter adds processing overhead. Only request fields you need:
- Base response: ~50-100ms
+ include_ordered_task_names: +50ms for 20+ tasks+ include_dynamic_data: +100-500ms (calls external APIs)+ include_output_schemas: +10-50ms+ include_validation_errors: No overhead (always validated)
Complete flow definition in DSL format. May be enriched with additional fields when using expansion parameters (include_dynamic_data, include_output_schemas). Enriched fields are added to each task within definition.tasks[].
Human-readable flow name
Whether this is the latest version of the flow
Organization that owns this flow
Opaque token for the stored state of this flow version: <version>:<hash of the stored definition>. It changes on every definition write, including saves that keep the version (task moves, retitles). Send it back as expected_revision on PUT /definition, PUT /task or POST /versions/{version}/restore to save only if nobody changed the flow since you read it; a stale value returns 409 revision_conflict. Never stored; not affected by expansion parameters.
Flow lifecycle status. Values: 'draft' (editable), 'published' (ready for production use)
Flow version number. Increments on each update.
Required range:
x >= 1Number of queued, running or awaiting-input runs that hold a Human In The Loop task (either HITL task type) that is still pending or in progress. Runs paused for other input, such as webhook data, are not counted. Populated by the flows list; null when the caller's role cannot read review tasks.
Number of awaiting-input runs without an open Human In The Loop task, such as runs waiting on webhook data. Populated by the flows list; null when the caller's role cannot read review tasks.
Detailed flow description
Number of runs that failed, were cancelled or are being cancelled, or that have a failed task (such a run still ends completed unless the flow fails executions on task errors). Populated by the flows list when include_error_executions_count=true or sorting by it.
Total number of times this flow has been executed across all versions
Whether an organization admin hid this flow from the Hub. Populated by the flows list.
When any non-deleted run of this flow was last created or updated — the flow's last processing activity. Null when the flow has never run. Populated by the flows list.
Number of executions on the most recent flow version that has any runs — the dataset calibration samples. Only included when include_latest_version_executions_count=true.
Flow-level configuration settings
Show child attributes
Show child attributes
Topologically sorted list of task names in execution order. Only included when include_ordered_task_names=true. Useful for visualizing task dependencies and execution flow.
DSL validation errors if the flow definition is malformed. Only included when include_validation_errors=true. Empty list indicates a valid flow. Each error contains location and message details.
Show child attributes
Show child attributes