Workflows
Connect two workflow draft nodes
Add one edge between two nodes of a workflow’s editable draft through the Console builder’s connection checks.
POST
/
api
/
v3
/
workflows
/
{workflowId}
/
draft-edges
Connect two workflow draft nodes
curl --request POST \
--url https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fromNodeId": "<string>",
"toNodeId": "<string>",
"sourceHandle": "<string>",
"targetHandle": "<string>",
"condition": "<string>",
"label": "<string>",
"onError": true,
"description": "<string>",
"collectGroup": "<string>"
}
'import requests
url = "https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges"
payload = {
"fromNodeId": "<string>",
"toNodeId": "<string>",
"sourceHandle": "<string>",
"targetHandle": "<string>",
"condition": "<string>",
"label": "<string>",
"onError": True,
"description": "<string>",
"collectGroup": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fromNodeId: '<string>',
toNodeId: '<string>',
sourceHandle: '<string>',
targetHandle: '<string>',
condition: '<string>',
label: '<string>',
onError: true,
description: '<string>',
collectGroup: '<string>'
})
};
fetch('https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges', 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://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fromNodeId' => '<string>',
'toNodeId' => '<string>',
'sourceHandle' => '<string>',
'targetHandle' => '<string>',
'condition' => '<string>',
'label' => '<string>',
'onError' => true,
'description' => '<string>',
'collectGroup' => '<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://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges"
payload := strings.NewReader("{\n \"fromNodeId\": \"<string>\",\n \"toNodeId\": \"<string>\",\n \"sourceHandle\": \"<string>\",\n \"targetHandle\": \"<string>\",\n \"condition\": \"<string>\",\n \"label\": \"<string>\",\n \"onError\": true,\n \"description\": \"<string>\",\n \"collectGroup\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fromNodeId\": \"<string>\",\n \"toNodeId\": \"<string>\",\n \"sourceHandle\": \"<string>\",\n \"targetHandle\": \"<string>\",\n \"condition\": \"<string>\",\n \"label\": \"<string>\",\n \"onError\": true,\n \"description\": \"<string>\",\n \"collectGroup\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fromNodeId\": \"<string>\",\n \"toNodeId\": \"<string>\",\n \"sourceHandle\": \"<string>\",\n \"targetHandle\": \"<string>\",\n \"condition\": \"<string>\",\n \"label\": \"<string>\",\n \"onError\": true,\n \"description\": \"<string>\",\n \"collectGroup\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"workflowId": "<string>",
"draftId": "<string>",
"edge": {
"edgeId": "<string>",
"fromNodeId": "<string>",
"toNodeId": "<string>",
"createdAt": 123,
"updatedAt": 123,
"sourceHandle": "<string>",
"targetHandle": "<string>",
"condition": "<string>",
"label": "<string>",
"onError": true,
"description": "<string>",
"collectGroup": "<string>"
}
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "bad_request",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "resource_missing",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "conflict",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unprocessable",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "internal_error",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.
v2 compatibility notes
POST /api/v2/workflows/createDraftEdge
Adds one edge between two nodes of the workflow’s editable draft after the Console builder’s connection checks: no self-loop, at most one edge per ordered node pair, a known router handle, matching output and input types, and a valid outcome error edge. A cycle is not refused here, just as in the builder; draft validation reports it before publish.
Authentication
External App credential or platform API key. Requires permissionworkflows:write, and the caller must hold both workflows:read and workflows:write at the workflow’s home org unit. Any External App or platform API key with those grants may edit; who created the workflow lends no authority. The org unit a request acts from is not the workflow’s home.
Body
Handles are set only here. To re-point an edge, delete it and create a new one.Responses
201 with:
The edge as getDraftGraph returns it.
Errors
| Status | Code | When |
|---|---|---|
400 | bad_request | Malformed JSON, an unknown or Console-only key, a wrong type. Message: Invalid workflow draft graph body. |
403 | permission_denied | The credential’s scopes do not include workflows:write. |
404 | resource_missing | The workflow id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks workflows:read and workflows:write at its home: Workflow not found. |
422 | unprocessable | A connection check refuses the edge, with its message (for example Self-loop edges are not allowed.). Endpoints that are not nodes of this draft answer Edge endpoints must be nodes of this draft. A draft that already holds 400 edges, or more than 200 nodes, answers This draft is too large to edit through the API; edit it in the Console. |
409 | idempotency_result_unavailable | A keyed repeat whose recorded result cannot be disclosed now. |
500 | internal_error | Unexpected error. |
Retries
Send anIdempotency-Key header to retry safely. Within 24 hours, the same key and body return the recorded status and body, with Idempotency-Replayed: true, while the caller still holds workflows:write and can read the workflow. Otherwise the repeat answers 409 idempotency_result_unavailable and does not write again. A new key is a new write. Without a key, a retried create meets the node-name rule (409) or the one-edge-per-pair rule (422), and a retried delete answers 404. If an outcome is unknown, read getDraftGraph before acting again.Authorizations
BearerAuthPlatformApiKeyPersonalKey
Body
application/json
⌘I
Connect two workflow draft nodes
curl --request POST \
--url https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fromNodeId": "<string>",
"toNodeId": "<string>",
"sourceHandle": "<string>",
"targetHandle": "<string>",
"condition": "<string>",
"label": "<string>",
"onError": true,
"description": "<string>",
"collectGroup": "<string>"
}
'import requests
url = "https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges"
payload = {
"fromNodeId": "<string>",
"toNodeId": "<string>",
"sourceHandle": "<string>",
"targetHandle": "<string>",
"condition": "<string>",
"label": "<string>",
"onError": True,
"description": "<string>",
"collectGroup": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fromNodeId: '<string>',
toNodeId: '<string>',
sourceHandle: '<string>',
targetHandle: '<string>',
condition: '<string>',
label: '<string>',
onError: true,
description: '<string>',
collectGroup: '<string>'
})
};
fetch('https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges', 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://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fromNodeId' => '<string>',
'toNodeId' => '<string>',
'sourceHandle' => '<string>',
'targetHandle' => '<string>',
'condition' => '<string>',
'label' => '<string>',
'onError' => true,
'description' => '<string>',
'collectGroup' => '<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://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges"
payload := strings.NewReader("{\n \"fromNodeId\": \"<string>\",\n \"toNodeId\": \"<string>\",\n \"sourceHandle\": \"<string>\",\n \"targetHandle\": \"<string>\",\n \"condition\": \"<string>\",\n \"label\": \"<string>\",\n \"onError\": true,\n \"description\": \"<string>\",\n \"collectGroup\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fromNodeId\": \"<string>\",\n \"toNodeId\": \"<string>\",\n \"sourceHandle\": \"<string>\",\n \"targetHandle\": \"<string>\",\n \"condition\": \"<string>\",\n \"label\": \"<string>\",\n \"onError\": true,\n \"description\": \"<string>\",\n \"collectGroup\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.forge.gloo.com/api/v3/workflows/{workflowId}/draft-edges")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fromNodeId\": \"<string>\",\n \"toNodeId\": \"<string>\",\n \"sourceHandle\": \"<string>\",\n \"targetHandle\": \"<string>\",\n \"condition\": \"<string>\",\n \"label\": \"<string>\",\n \"onError\": true,\n \"description\": \"<string>\",\n \"collectGroup\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"workflowId": "<string>",
"draftId": "<string>",
"edge": {
"edgeId": "<string>",
"fromNodeId": "<string>",
"toNodeId": "<string>",
"createdAt": 123,
"updatedAt": 123,
"sourceHandle": "<string>",
"targetHandle": "<string>",
"condition": "<string>",
"label": "<string>",
"onError": true,
"description": "<string>",
"collectGroup": "<string>"
}
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "bad_request",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "resource_missing",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "conflict",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unprocessable",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "internal_error",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}
