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>"
}
}
'{
"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>"
}
}
'{
"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.Documentation Index
Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
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