Update Definition

POST /v2/workflow/definitions/update

Update Definition

cURL

curl --request POST \
  --url https://api.velt.dev/v2/workflow/definitions/update \
  --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>",
    "ifVersion": 123,
    "name": "<string>",
    "description": "<string>",
    "nodes": [
      {}
    ],
    "edges": [
      {}
    ],
    "groups": [
      {}
    ],
    "loops": [
      {}
    ],
    "triggers": [
      {}
    ],
    "tags": [
      "<string>"
    ],
    "custom": {},
    "organizationId": "<string>",
    "documentId": "<string>"
  }
}
'

{
  "result": {
    "definitionId": "marketing-copy-approval",
    "name": "Marketing copy approval (Q2 revision)",
    "description": null,
    "version": 2,
    "scope": { "level": "apiKey", "organizationId": null, "documentId": null },
    "nodes": [],
    "edges": [],
    "groups": [],
    "triggers": null,
    "tags": null,
    "custom": null,
    "createdAt": 1731432000000,
    "updatedAt": 1731518400000,
    "status": "active"
  }
}

Use this API to update an existing workflow definition. Atomically increments the version, snapshots the prior content, and rejects if the stored version mismatches ifVersion. In-flight executions keep running on the version they started with.

Endpoint

POST https://api.velt.dev/v2/workflow/definitions/update

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

Accepts every field from Create Definition plus:

data · object · required

Show properties

definitionId · string · required

The definition to update.

ifVersion · integer · required

Optimistic-locking version. Must equal the stored definition’s current version. The update is rejected if the stored version has advanced since you last read it.

name · string

1–200 chars.

description · string

0–2000 chars.

nodes · array

1–100 nodes.

edges · array

0–500 edges.

groups · array

0–100 parallel-group definitions.

loops · array

0–20 loop region declarations. See loop regions on the Customize Behavior page for the full schema and linter rules.

triggers · array

0–50 trigger declarations. Each trigger has the shape { 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.

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 eventName → definitionId.

tags · string[]

0–20 tags, each ≤ 64 chars.

custom · object

Free-form metadata.

organizationId · string

Required when scoped to an organization or document.

documentId · string

Required when scoped to a document.

Every successful update increments version and snapshots the prior content. In-flight executions are immune to updates — they keep running on the pinned definitionVersion from their dispatch.

Example Requests

Rename a definition

{
  "data": {
    "definitionId": "marketing-copy-approval",
    "ifVersion": 1,
    "name": "Marketing copy approval (Q2 revision)"
  }
}

Response

Success Response

{
  "result": {
    "definitionId": "marketing-copy-approval",
    "name": "Marketing copy approval (Q2 revision)",
    "description": null,
    "version": 2,
    "scope": { "level": "apiKey", "organizationId": null, "documentId": null },
    "nodes": [ /* current */ ],
    "edges": [ /* current */ ],
    "groups": [ /* current */ ],
    "triggers": null,
    "tags": null,
    "custom": null,
    "createdAt": 1731432000000,
    "updatedAt": 1731518400000,
    "status": "active"
  }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "FAILED_PRECONDITION"
  }
}

Errors: NOT_FOUND (definition does not exist) / FAILED_PRECONDITION (ifVersion mismatch) / INVALID_ARGUMENT (schema or linter failure).

{
  "result": {
    "definitionId": "marketing-copy-approval",
    "name": "Marketing copy approval (Q2 revision)",
    "description": null,
    "version": 2,
    "scope": { "level": "apiKey", "organizationId": null, "documentId": null },
    "nodes": [],
    "edges": [],
    "groups": [],
    "triggers": null,
    "tags": null,
    "custom": null,
    "createdAt": 1731432000000,
    "updatedAt": 1731518400000,
    "status": "active"
  }
}