Retrieve a flow by ID

curl --request GET \
  --url https://flows.super.ai/api/flows/{flow_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://flows.super.ai/api/flows/{flow_id}"

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/flows/{flow_id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/flows/{flow_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/flows/{flow_id}")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/flows/{flow_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

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",
  "status": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "version": 2,
  "description": "<string>",
  "flow_executions_count": 0,
  "settings": {
    "reexecute_on_update": false,
    "ttl": {}
  },
  "task_names": [
    "<string>"
  ],
  "validation_errors": [
    {
      "input": "<unknown>",
      "loc": [
        123
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "url": "<string>"
    }
  ]
}

flows

Retrieve a flow by ID

Retrieve a specific flow by ID.

Returns the latest version of a flow with its complete definition, metadata, and optional computed fields. This endpoint is typically used when displaying flow details or preparing to execute a flow.

Behavior

Always returns the latest version unless a specific version is requested via /flows/{flow_id}/versions/{version}
Use expansion parameters to include computed fields (see FlowResponse model docs)

Use Cases

Display flow details in your application UI
Retrieve flow definition before execution
Check flow validation status and errors

GET

api

flows

{flow_id}

Retrieve a flow by ID

curl --request GET \
  --url https://flows.super.ai/api/flows/{flow_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://flows.super.ai/api/flows/{flow_id}"

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/flows/{flow_id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/flows/{flow_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/flows/{flow_id}")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/flows/{flow_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

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",
  "status": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "version": 2,
  "description": "<string>",
  "flow_executions_count": 0,
  "settings": {
    "reexecute_on_update": false,
    "ttl": {}
  },
  "task_names": [
    "<string>"
  ],
  "validation_errors": [
    {
      "input": "<unknown>",
      "loc": [
        123
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "url": "<string>"
    }
  ]
}

Authorizations

X-API-Key

string

header

required

API key authentication. Include your API key in the X-API-Key header as: X-API-Key YOUR_API_KEY

Example:

X-API-Key: saf_1234567890

Authorization

string

header

required

JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Path Parameters

flow_id

string<uuid>

required

Query Parameters

include_ordered_task_names

boolean

default:false

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_validation_errors

boolean

default:false

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_dynamic_data

boolean

default:false

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_output_schemas

boolean

default:false

Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections.

include_input_schema

boolean

default:false

Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building.

Response

Flow successfully retrieved

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: Adds task_names field with topological sort
include_validation_errors: Adds validation_errors field if flow is invalid
include_dynamic_data: Enriches each task in definition with runtime config options
include_output_schemas: Enriches each task in definition with 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)

created_at

string<date-time>

required

definition

Definition · object

required

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[].

display_name

string

required

Human-readable flow name

string<uuid>

required

is_latest

boolean

required

Whether this is the latest version of the flow

modified_by

string

required

organization_id

string<uuid>

required

Organization that owns this flow

status

string

required

Flow lifecycle status. Values: 'draft' (editable), 'published' (ready for production use)

updated_at

string<date-time>

required

version

integer

required

Flow version number. Increments on each update.

Required range: x >= 1

description

string | null

Detailed flow description

flow_executions_count

integer

default:0

Total number of times this flow has been executed across all versions

settings

FlowSettings · object | null

Flow-level configuration settings

Show child attributes

task_names

string[] | null

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.

validation_errors

ErrorDetails · object[] | null

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

Generate file download URL Delete a flow

Overview

Endpoints

Retrieve a flow by ID

Behavior

Use Cases

Authorizations

Path Parameters

Query Parameters

Response

Expansion Parameters

Performance Considerations