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

# Get Definition

Use this API to fetch a workflow definition. Returns the full `DefinitionView`. Filters out tombstoned definitions.

A read response round-trips into [Create Definition](https://velt.dev/docs/api-reference/rest-apis/v2/approval-engine/definitions/create-definition.md) once you change `definitionId` and strip the server-owned `version`, `createdAt`, `updatedAt`, `status`, and `compiled` fields. Strip the explicit nulls too. Every optional field you never set comes back as `null`: `description`, `groups`, `triggers`, `tags`, `custom`, and `organizationId` / `documentId` inside `scope`. Create takes those fields as absent or as real values, never as `null`, so a leftover `null` fails the request with `INVALID_ARGUMENT`. See [Duplicating a workflow](https://velt.dev/docs/ai/approval-engine/patterns.md#duplicating-a-workflow).

# Endpoint

`POST https://api.velt.dev/v2/workflow/definitions/get`

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

The definition to fetch.

**organizationId** `string`

Accepted but ignored. The lookup is keyed by `definitionId` alone under your API key.

**documentId** `string`

Accepted but ignored. A get succeeds for `apiKey`-scoped, `organization`-scoped, and `document`-scoped definitions without it.

## **Example Requests**

#### Get a definition

```JSON theme={null}
{
  "data": {
    "definitionId": "marketing-copy-approval"
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "definitionId": "marketing-copy-approval",
    "name": "Marketing copy approval",
    "description": null,
    "version": 1,
    "scope": { "level": "apiKey", "organizationId": null, "documentId": null },
    "nodes": [
      { "nodeId": "agent-draft", "type": "agent", "config": { "agentId": "copy-agent-v1", "urlPath": "documentUrl" } },
      { "nodeId": "human-review", "type": "human", "config": { "reviewers": [{ "userId": "u_reviewer_01", "mandatory": true }] } },
      { "nodeId": "agent-publish", "type": "agent", "config": { "agentId": "publish-agent-v1", "urlPath": "documentUrl" } },
      { "nodeId": "agent-rework", "type": "agent", "config": { "agentId": "rework-agent-v1", "urlPath": "documentUrl" } }
    ],
    "edges": [
      { "from": "agent-draft", "to": "human-review" },
      { "from": "human-review", "to": "agent-publish", "on": "approve" },
      { "from": "human-review", "to": "agent-rework", "on": "reject" }
    ],
    "groups": null,
    "compiled": {
      "forwardEdges": [
        { "from": "agent-draft", "to": "human-review", "role": "always", "when": null },
        { "from": "human-review", "to": "agent-publish", "role": "approve", "when": { "op": "eq", "args": [{ "var": "output.decision" }, "approve"] } },
        { "from": "human-review", "to": "agent-rework", "role": "reject", "when": { "op": "eq", "args": [{ "var": "output.decision" }, "reject"] } }
      ],
      "loops": []
    },
    "triggers": null,
    "tags": null,
    "custom": null,
    "createdAt": 1731432000000,
    "updatedAt": 1731432000000,
    "status": "active"
  }
}
```

#### The `compiled` block

`compiled` is a read-only block on every `DefinitionView`. The authored `edges` echo `sourceEdges` byte-for-byte; `compiled` is the server-derived runtime view used to drive execution. Both are additive: render a workflow graph directly from `compiled.forwardEdges` instead of re-implementing group expansion client-side.

**compiled** `object`

**properties**

**forwardEdges** `array`

The runtime forward-edge list. Group endpoints are expanded to per-member compiled edges and `on` roles are compiled to a predicate AST. Each entry:

| Field | Type | Notes |
| - | - | - |
| `from` | string | Resolved node id. |
| `to` | string | Resolved node id. |
| `role` | `approve` / `reject` / `always` / `exhausted` / `custom` | The authored `on` role. |
| `when` | `JsonAst \| null` | Deterministic predicate AST; `null` for `always`. |
| `fromGroupId` | string | Present when the authored `from` was a group. |
| `toGroupId` | string | Present when the authored `to` was a group. |

**loops** `array`

The server-derived loop regions. Each entry:

| Field | Type | Notes |
| - | - | - |
| `loopId` | string | Stable identifier for the derived loop. |
| `entryNodeId` | string | Node re-entered on each iteration. |
| `bodyNodeIds` | string\[] | Nodes inside the loop's iteration scope. |
| `maxIterations` | number | Hard cap per execution (from the reject edge's `loop`). |
| `onExhausted` | `{ routeToNodeId: string } \| null` | Sibling `on:"exhausted"` target, or `null`. |

#### Failure Response

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

**Errors:** `NOT_FOUND` (definition does not exist or is tombstoned) / `INVALID_ARGUMENT`.

```js theme={null}
{
  "result": {
    "definitionId": "marketing-copy-approval",
    "name": "Marketing copy approval",
    "description": null,
    "version": 1,
    "scope": { "level": "apiKey", "organizationId": null, "documentId": null },
    "nodes": [
      { "nodeId": "agent-draft", "type": "agent", "config": { "agentId": "copy-agent-v1", "urlPath": "documentUrl" } }
    ],
    "edges": [],
    "groups": null,
    "compiled": { "forwardEdges": [], "loops": [] },
    "triggers": null,
    "tags": null,
    "custom": null,
    "createdAt": 1731432000000,
    "updatedAt": 1731432000000,
    "status": "active"
  }
}
```


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