Create Definition
curl --request POST \
--url https://api.velt.dev/v2/workflow/definitions/create \
--header 'Content-Type: application/json' \
--header 'x-velt-api-key: <x-velt-api-key>' \
--header 'x-velt-auth-token: <x-velt-auth-token>' \
--data '
{
"data": {
"definitionId": "<string>",
"name": "<string>",
"description": "<string>",
"scope": {},
"nodes": [
{}
],
"edges": [
{}
],
"groups": [
{}
],
"loops": [
{}
],
"triggers": [
{}
],
"tags": [
"<string>"
],
"custom": {},
"organizationId": "<string>",
"documentId": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/workflow/definitions/create"
payload = { "data": {
"definitionId": "<string>",
"name": "<string>",
"description": "<string>",
"scope": {},
"nodes": [{}],
"edges": [{}],
"groups": [{}],
"loops": [{}],
"triggers": [{}],
"tags": ["<string>"],
"custom": {},
"organizationId": "<string>",
"documentId": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
definitionId: '<string>',
name: '<string>',
description: '<string>',
scope: {},
nodes: [{}],
edges: [{}],
groups: [{}],
loops: [{}],
triggers: [{}],
tags: ['<string>'],
custom: {},
organizationId: '<string>',
documentId: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/workflow/definitions/create', 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.velt.dev/v2/workflow/definitions/create",
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([
'data' => [
'definitionId' => '<string>',
'name' => '<string>',
'description' => '<string>',
'scope' => [
],
'nodes' => [
[
]
],
'edges' => [
[
]
],
'groups' => [
[
]
],
'loops' => [
[
]
],
'triggers' => [
[
]
],
'tags' => [
'<string>'
],
'custom' => [
],
'organizationId' => '<string>',
'documentId' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$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.velt.dev/v2/workflow/definitions/create"
payload := strings.NewReader("{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"scope\": {},\n \"nodes\": [\n {}\n ],\n \"edges\": [\n {}\n ],\n \"groups\": [\n {}\n ],\n \"loops\": [\n {}\n ],\n \"triggers\": [\n {}\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"custom\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-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.velt.dev/v2/workflow/definitions/create")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"scope\": {},\n \"nodes\": [\n {}\n ],\n \"edges\": [\n {}\n ],\n \"groups\": [\n {}\n ],\n \"loops\": [\n {}\n ],\n \"triggers\": [\n {}\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"custom\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/workflow/definitions/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"scope\": {},\n \"nodes\": [\n {}\n ],\n \"edges\": [\n {}\n ],\n \"groups\": [\n {}\n ],\n \"loops\": [\n {}\n ],\n \"triggers\": [\n {}\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"custom\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"definitionId": "marketing-copy-approval",
"name": "Marketing copy approval",
"description": null,
"version": 1,
"scope": { "level": "apiKey", "organizationId": null, "documentId": null },
"nodes": [],
"edges": [],
"groups": [],
"triggers": null,
"tags": null,
"custom": null,
"createdAt": 1731432000000,
"updatedAt": 1731432000000,
"status": "active"
}
}
Definitions
Create Definition
POST
/
v2
/
workflow
/
definitions
/
create
Create Definition
curl --request POST \
--url https://api.velt.dev/v2/workflow/definitions/create \
--header 'Content-Type: application/json' \
--header 'x-velt-api-key: <x-velt-api-key>' \
--header 'x-velt-auth-token: <x-velt-auth-token>' \
--data '
{
"data": {
"definitionId": "<string>",
"name": "<string>",
"description": "<string>",
"scope": {},
"nodes": [
{}
],
"edges": [
{}
],
"groups": [
{}
],
"loops": [
{}
],
"triggers": [
{}
],
"tags": [
"<string>"
],
"custom": {},
"organizationId": "<string>",
"documentId": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/workflow/definitions/create"
payload = { "data": {
"definitionId": "<string>",
"name": "<string>",
"description": "<string>",
"scope": {},
"nodes": [{}],
"edges": [{}],
"groups": [{}],
"loops": [{}],
"triggers": [{}],
"tags": ["<string>"],
"custom": {},
"organizationId": "<string>",
"documentId": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
definitionId: '<string>',
name: '<string>',
description: '<string>',
scope: {},
nodes: [{}],
edges: [{}],
groups: [{}],
loops: [{}],
triggers: [{}],
tags: ['<string>'],
custom: {},
organizationId: '<string>',
documentId: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/workflow/definitions/create', 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.velt.dev/v2/workflow/definitions/create",
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([
'data' => [
'definitionId' => '<string>',
'name' => '<string>',
'description' => '<string>',
'scope' => [
],
'nodes' => [
[
]
],
'edges' => [
[
]
],
'groups' => [
[
]
],
'loops' => [
[
]
],
'triggers' => [
[
]
],
'tags' => [
'<string>'
],
'custom' => [
],
'organizationId' => '<string>',
'documentId' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$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.velt.dev/v2/workflow/definitions/create"
payload := strings.NewReader("{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"scope\": {},\n \"nodes\": [\n {}\n ],\n \"edges\": [\n {}\n ],\n \"groups\": [\n {}\n ],\n \"loops\": [\n {}\n ],\n \"triggers\": [\n {}\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"custom\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-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.velt.dev/v2/workflow/definitions/create")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"scope\": {},\n \"nodes\": [\n {}\n ],\n \"edges\": [\n {}\n ],\n \"groups\": [\n {}\n ],\n \"loops\": [\n {}\n ],\n \"triggers\": [\n {}\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"custom\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/workflow/definitions/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"scope\": {},\n \"nodes\": [\n {}\n ],\n \"edges\": [\n {}\n ],\n \"groups\": [\n {}\n ],\n \"loops\": [\n {}\n ],\n \"triggers\": [\n {}\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"custom\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"definitionId": "marketing-copy-approval",
"name": "Marketing copy approval",
"description": null,
"version": 1,
"scope": { "level": "apiKey", "organizationId": null, "documentId": null },
"nodes": [],
"edges": [],
"groups": [],
"triggers": null,
"tags": null,
"custom": null,
"createdAt": 1731432000000,
"updatedAt": 1731432000000,
"status": "active"
}
}
Use this API to register a new workflow definition (the static blueprint of nodes, edges, and optional parallel groups). Definitions are linted at write time — invalid graphs are rejected with an explicit linter code.
Errors:
Endpoint
POST https://api.velt.dev/v2/workflow/definitions/create
Headers
Your API key.
Your Auth Token.
Body
Params
Show properties
Show properties
^[a-z0-9][a-z0-9-]{2,63}$. Stable identifier for this definition.1–200 chars. Human-readable label.
0–2000 chars.
Defaults to
{ level: "apiKey" }. Options:{ level: "apiKey" }— workspace-wide.{ level: "organization", organizationId: "<id>" }— bound to one organization.organizationIdis required (returnsINVALID_ARGUMENTif omitted).{ level: "document", organizationId: "<id>", documentId: "<id>" }— bound to one document under an organization. Both fields required.
scope.organizationId / scope.documentId, the values are the engine’s server-namespaced ids (hashed from your client ids), not the literal strings you sent. Don’t try to use them as your own identifiers — keep your client ids on your side.1–100 nodes. Each node has
nodeId, type (agent / human / webhook), and a config block. See node configuration details in Customize Behavior. Each node also accepts an optional slaMs (integer, ms) — SLA deadline for the step.0–500 edges. Each edge:
{ from, to, when? }. The optional when expression is evaluated against the source step’s output — see edge gating expressions.0–100 parallel-group definitions. See parallel groups and quorum policies.
0–20 loop region declarations. A loop region lets a workflow re-enter an earlier node when a reviewer rejects, with previous-attempt context threaded forward and a hard cap on iterations. See loop regions for the full schema, body-shape constraints, and linter rules.
0–50 trigger declarations. Each trigger has the shape
Triggers are descriptive metadata in v1 — the engine does not auto-dispatch from them. Use them to label which definition belongs to which application event so your own dispatcher can resolve
{ triggerId, eventName?, filters? }:| Field | Type | Required | Description |
|---|---|---|---|
triggerId | string | yes | 1–128 chars. Stable identifier for this trigger. |
eventName | string | no | ≤ 128 chars. The event name your application emits when the workflow should dispatch. |
filters | object | no | Free-form filter map; consumed by your dispatch wrapper to decide whether to fire this trigger. |
eventName → definitionId.0–20 tags, each ≤ 64 chars.
Free-form metadata.
Required when
scope.level is organization or document.Required when
scope.level is document.Node object example
{
"nodeId": "brand-check",
"type": "agent",
"config": { "agentId": "brand-agent-v1", "blocking": false, "requireNonEmptyOutput": true },
"slaMs": 3600000
}
Edge object example
{ "from": "brand-check", "to": "legal-review", "when": "output.passesBrandCheck == true" }
Example Requests
Create a marketing-copy approval workflow
{
"data": {
"definitionId": "marketing-copy-approval",
"name": "Marketing copy approval",
"scope": { "level": "apiKey" },
"nodes": [
{ "nodeId": "agent-draft", "type": "agent", "config": { "agentId": "copy-agent-v1" } },
{ "nodeId": "human-legal", "type": "human", "config": { "reviewers": [{ "userId": "u_legal_01", "mandatory": true }] } },
{ "nodeId": "human-brand", "type": "human", "config": { "reviewers": [{ "userId": "u_brand_01", "mandatory": true }] } },
{ "nodeId": "agent-publish", "type": "agent", "config": { "agentId": "publish-agent-v1" } }
],
"edges": [
{ "from": "agent-draft", "to": "human-legal" },
{ "from": "agent-draft", "to": "human-brand" },
{ "from": "human-legal", "to": "agent-publish" },
{ "from": "human-brand", "to": "agent-publish" }
],
"groups": [{
"groupId": "parallel-review",
"memberNodeIds": ["human-legal", "human-brand"],
"expectedSteps": 2,
"quorum": 2,
"onQuorumMet": "joinOnQuorum"
}]
}
}
Response
Success Response
{
"result": {
"definitionId": "marketing-copy-approval",
"name": "Marketing copy approval",
"description": null,
"version": 1,
"scope": { "level": "apiKey", "organizationId": null, "documentId": null },
"nodes": [ /* echoed back with resolved defaults */ ],
"edges": [ /* echoed back with when: null for unset gates */ ],
"groups": [ /* echoed back */ ],
"triggers": null,
"tags": null,
"custom": null,
"createdAt": 1731432000000,
"updatedAt": 1731432000000,
"status": "active"
}
}
Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
INVALID_ARGUMENT (schema or linter failure; message includes the linter code) / ALREADY_EXISTS (definitionId already in use).
{
"result": {
"definitionId": "marketing-copy-approval",
"name": "Marketing copy approval",
"description": null,
"version": 1,
"scope": { "level": "apiKey", "organizationId": null, "documentId": null },
"nodes": [],
"edges": [],
"groups": [],
"triggers": null,
"tags": null,
"custom": null,
"createdAt": 1731432000000,
"updatedAt": 1731432000000,
"status": "active"
}
}
Was this page helpful?
⌘I