Dispatch Execution
curl --request POST \
--url https://api.velt.dev/v2/workflow/executions/dispatch \
--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>",
"idempotencyKey": "<string>",
"correlationId": "<string>",
"triggerContext": {},
"organizationId": "<string>",
"documentId": "<string>",
"folderId": "<string>",
"webhookUrl": "<string>",
"webhookSecret": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/workflow/executions/dispatch"
payload = { "data": {
"definitionId": "<string>",
"idempotencyKey": "<string>",
"correlationId": "<string>",
"triggerContext": {},
"organizationId": "<string>",
"documentId": "<string>",
"folderId": "<string>",
"webhookUrl": "<string>",
"webhookSecret": "<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>',
idempotencyKey: '<string>',
correlationId: '<string>',
triggerContext: {},
organizationId: '<string>',
documentId: '<string>',
folderId: '<string>',
webhookUrl: '<string>',
webhookSecret: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/workflow/executions/dispatch', 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/executions/dispatch",
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>',
'idempotencyKey' => '<string>',
'correlationId' => '<string>',
'triggerContext' => [
],
'organizationId' => '<string>',
'documentId' => '<string>',
'folderId' => '<string>',
'webhookUrl' => '<string>',
'webhookSecret' => '<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/executions/dispatch"
payload := strings.NewReader("{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"idempotencyKey\": \"<string>\",\n \"correlationId\": \"<string>\",\n \"triggerContext\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"folderId\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"webhookSecret\": \"<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/executions/dispatch")
.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 \"idempotencyKey\": \"<string>\",\n \"correlationId\": \"<string>\",\n \"triggerContext\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"folderId\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"webhookSecret\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/workflow/executions/dispatch")
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 \"idempotencyKey\": \"<string>\",\n \"correlationId\": \"<string>\",\n \"triggerContext\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"folderId\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"webhookSecret\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"executionId": "exec_1777374504255_xzy43k9q",
"correlationId": "corr_campaign_42",
"deduplicated": false
}
}
Executions
Dispatch Execution
POST
/
v2
/
workflow
/
executions
/
dispatch
Dispatch Execution
curl --request POST \
--url https://api.velt.dev/v2/workflow/executions/dispatch \
--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>",
"idempotencyKey": "<string>",
"correlationId": "<string>",
"triggerContext": {},
"organizationId": "<string>",
"documentId": "<string>",
"folderId": "<string>",
"webhookUrl": "<string>",
"webhookSecret": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/workflow/executions/dispatch"
payload = { "data": {
"definitionId": "<string>",
"idempotencyKey": "<string>",
"correlationId": "<string>",
"triggerContext": {},
"organizationId": "<string>",
"documentId": "<string>",
"folderId": "<string>",
"webhookUrl": "<string>",
"webhookSecret": "<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>',
idempotencyKey: '<string>',
correlationId: '<string>',
triggerContext: {},
organizationId: '<string>',
documentId: '<string>',
folderId: '<string>',
webhookUrl: '<string>',
webhookSecret: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/workflow/executions/dispatch', 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/executions/dispatch",
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>',
'idempotencyKey' => '<string>',
'correlationId' => '<string>',
'triggerContext' => [
],
'organizationId' => '<string>',
'documentId' => '<string>',
'folderId' => '<string>',
'webhookUrl' => '<string>',
'webhookSecret' => '<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/executions/dispatch"
payload := strings.NewReader("{\n \"data\": {\n \"definitionId\": \"<string>\",\n \"idempotencyKey\": \"<string>\",\n \"correlationId\": \"<string>\",\n \"triggerContext\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"folderId\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"webhookSecret\": \"<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/executions/dispatch")
.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 \"idempotencyKey\": \"<string>\",\n \"correlationId\": \"<string>\",\n \"triggerContext\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"folderId\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"webhookSecret\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/workflow/executions/dispatch")
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 \"idempotencyKey\": \"<string>\",\n \"correlationId\": \"<string>\",\n \"triggerContext\": {},\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"folderId\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"webhookSecret\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"executionId": "exec_1777374504255_xzy43k9q",
"correlationId": "corr_campaign_42",
"deduplicated": false
}
}
Use this API to start a new execution of a workflow definition. Dispatch pins the current definition version, stamps a correlation ID and idempotency key, and enqueues the first step(s).
Errors:
Endpoint
POST https://api.velt.dev/v2/workflow/executions/dispatch
Headers
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
object
required
Show properties
Show properties
string
required
Must exist with
status: "active".string
^[A-Za-z0-9:_\-.]{1,200}$. Replaying with the same key returns the prior executionId.string
^[A-Za-z0-9:_\-.]{1,200}$. Server-generated if omitted.object
Free-form payload exposed as
execution.input.* in edge expressions.string
Organization the execution runs against. Agent nodes use it when they call the agent. It is not validated against the definition’s
scope. Dispatch stores it on the execution, but no read endpoint returns it, so treat it as write-only.string
Document the execution runs against. Agent nodes use it when they call the agent. It is not validated against the definition’s
scope. Dispatch stores it on the execution, but no read endpoint returns it, so treat it as write-only.string
Optional folder association.
string
HTTPS-only per-execution receiver. Must be paired with
webhookSecret.string
16–512 chars. Used to sign webhook deliveries with HMAC-SHA256.
webhookUrl is validated at the schema boundary and re-checked at delivery time. Scheme must be https://. Literal IP hosts in loopback, private (RFC 1918), link-local, or IPv4-mapped-private ranges are rejected. Forbidden hostnames include localhost, metadata.google.internal, metadata, and any *.internal. At delivery, DNS resolution is repeated; if any resolved address is private, the request is not sent. Redirects are never followed.Example Requests
Dispatch with idempotency and webhook
{
"data": {
"definitionId": "marketing-copy-approval",
"idempotencyKey": "campaign-42-dispatch",
"correlationId": "corr_campaign_42",
"triggerContext": { "assetId": "asset_8f3", "campaign": "Q2 launch" },
"webhookUrl": "https://hooks.acme.com/velt/approvals",
"webhookSecret": "whsec_9a8fS2l..."
}
}
Response
Success Response
{
"result": {
"executionId": "exec_1777374504255_xzy43k9q",
"correlationId": "corr_campaign_42",
"deduplicated": false
}
}
deduplicated: true indicates a replay (including in-tx contention): the returned executionId is the original execution’s id.
Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "NOT_FOUND"
}
}
NOT_FOUND (no definition with that definitionId) / FAILED_PRECONDITION (the definition is tombstoned, or it has no root nodes) / INVALID_ARGUMENT (schema validation, including webhookUrl and webhookSecret not both set).
A tombstoned definition returns FAILED_PRECONDITION, not NOT_FOUND. FAILED_PRECONDITION also covers the no-root-nodes case, so it does not identify a soft-deleted definition on its own.
{
"result": {
"executionId": "exec_1777374504255_xzy43k9q",
"correlationId": "corr_campaign_42",
"deduplicated": false
}
}
Was this page helpful?
⌘I