> ## 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.

# Dispatch Execution

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).

# Endpoint

`POST https://api.velt.dev/v2/workflow/executions/dispatch`

# Headers

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**definitionId** `string` *required*

Must exist with `status: "active"`.

**idempotencyKey** `string`

`^[A-Za-z0-9:_\-.]{1,200}$`. Replaying with the same key returns the prior `executionId`.

**correlationId** `string`

`^[A-Za-z0-9:_\-.]{1,200}$`. Server-generated if omitted.

**triggerContext** `object`

Free-form payload exposed as `execution.input.*` in edge expressions.

**organizationId** `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, and [Get Execution](https://velt.dev/docs/api-reference/rest-apis/v2/approval-engine/executions/get-execution.md) and [List Executions](https://velt.dev/docs/api-reference/rest-apis/v2/approval-engine/executions/list-executions.md) return it on the execution.

**documentId** `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, and [Get Execution](https://velt.dev/docs/api-reference/rest-apis/v2/approval-engine/executions/get-execution.md) and [List Executions](https://velt.dev/docs/api-reference/rest-apis/v2/approval-engine/executions/list-executions.md) return it on the execution.

**folderId** `string`

Optional folder association.

**webhookUrl** `string`

HTTPS-only per-execution receiver. Must be paired with `webhookSecret`.

**webhookSecret** `string`

16–512 chars. Used to sign webhook deliveries with HMAC-SHA256.

> [!WARNING]
>
> `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

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

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

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

**Errors:** `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.

```js theme={null}
{
  "result": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "correlationId": "corr_campaign_42",
    "deduplicated": false
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.