> ## Documentation Index
> Fetch the complete documentation index at: https://velt-mintlify-e6426361.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update approval definition (v2)

> Edit an existing approval workflow definition's nodes, edges, or parallel groups using the Velt v2 REST API. Changes are linted before being applied.

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

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

Accepts every field from [Create Definition](/api-reference/rest-apis/v2/approval-engine/definitions/create-definition) plus:

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="definitionId" type="string" required>
      The definition to update.
    </ParamField>

    <ParamField body="ifVersion" type="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.
    </ParamField>

    <ParamField body="name" type="string">
      1–200 chars.
    </ParamField>

    <ParamField body="description" type="string">
      0–2000 chars.
    </ParamField>

    <ParamField body="nodes" type="array">
      1–100 nodes.
    </ParamField>

    <ParamField body="edges" type="array">
      0–500 edges.
    </ParamField>

    <ParamField body="groups" type="array">
      0–100 parallel-group definitions.
    </ParamField>

    <ParamField body="loops" type="array">
      0–20 loop region declarations. See [loop regions](/ai/approval-engine/customize-behavior#loop-regions) on the Customize Behavior page for the full schema and linter rules.
    </ParamField>

    <ParamField body="triggers" type="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`.
    </ParamField>

    <ParamField body="tags" type="string[]">
      0–20 tags, each ≤ 64 chars.
    </ParamField>

    <ParamField body="custom" type="object">
      Free-form metadata.
    </ParamField>

    <ParamField body="organizationId" type="string">
      Required when scoped to an organization or document.
    </ParamField>

    <ParamField body="documentId" type="string">
      Required when scoped to a document.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  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.
</Note>

## **Example Requests**

#### Rename a definition

```JSON theme={null}
{
  "data": {
    "definitionId": "marketing-copy-approval",
    "ifVersion": 1,
    "name": "Marketing copy approval (Q2 revision)"
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "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

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "FAILED_PRECONDITION"
  }
}
```

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

<ResponseExample>
  ```js theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>