> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct Execution API for V2 Flows

> Trigger a V2 Flow directly via API, and update integrations that previously called a V1 workflow this way.

If your integration calls a workflow directly through the API — rather than triggering it from the UI, an agent, or a schedule — use this reference to call V2 Flows correctly, including when [migrating an existing V1 workflow](/tools/migrate-v1-workflows).

## Overview

V1 workflows execute through:

```text theme={null}
POST /actions/execute/direct
```

For a V2 Flow, use:

```text theme={null}
POST /tools/execute-workflow
```

<Warning>
  The V2 endpoint is not a drop-in payload replacement. The V2 Flow ID is sent as `tool_id`, and Flow inputs are sent as plain runtime values under `inputs`.
</Warning>

## Authentication

Provide your Odin API credentials as request headers:

```text theme={null}
X-API-KEY: <api-key>
X-API-SECRET: <api-secret>
Content-Type: application/json
```

<Warning>
  Never include real credentials in documentation, source control, tickets, or chat messages. Revoke and regenerate any credential that has been exposed.
</Warning>

## Request body

```json theme={null}
{
  "project_id": "<project-id>",
  "tool_id": "<v2-flow-id>",
  "inputs": {
    "<flow-input-name>": "<runtime-value>"
  },
  "execution_mode": "workflow",
  "mode": "manual"
}
```

Input names are case-sensitive — use the input name configured in the V2 Flow. For example, an input named `New Input 1` should be submitted as:

```json theme={null}
{
  "inputs": {
    "New Input 1": "I am Gaurav"
  }
}
```

Do not send the Flow input's full definition as the runtime value:

```json theme={null}
{
  "inputs": {
    "New Input 1": {
      "id": "new_input_1",
      "type": "string",
      "value": "I am Gaurav",
      "required": true
    }
  }
}
```

The `id`, `type`, `description`, and `required` fields belong to the stored Flow configuration — the execution request should contain only the value.

## Example

```bash theme={null}
curl --location 'https://api.getodin.ai/tools/execute-workflow' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-SECRET: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "project_id": "<project-id>",
    "tool_id": "<v2-flow-id>",
    "inputs": {
      "New Input 1": "I am Gaurav"
    },
    "execution_mode": "workflow",
    "mode": "manual"
  }'
```

## Executing the published version

Once the Flow has been published or promoted, add:

```json theme={null}
{
  "environment": "live"
}
```

This selects the version deployed to the live environment. Omit `environment` during initial testing, before the Flow has been published.

The endpoint waits for the complete execution result by default. You can supply this explicitly when needed:

```json theme={null}
{
  "return_response": true
}
```

## Response

A successful request returns an execution result:

```json theme={null}
{
  "success": true,
  "message": "Workflow executed successfully",
  "node_results": {},
  "execution_time_ms": 1250,
  "execution_id": "<execution-id>",
  "error": null
}
```

The contents of `node_results` depend on the nodes used by the Flow.

## Common errors

| Status                        | Meaning                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`            | The API key or secret is missing, invalid, or revoked                                                  |
| `402 Payment Required`        | The associated team doesn't have sufficient credits                                                    |
| `403 Forbidden`               | The API user isn't a project member or lacks permission to execute Flows                               |
| `404 Not Found`               | The `tool_id` doesn't exist or doesn't belong to the specified project                                 |
| `422 Unprocessable Entity`    | A required request field is missing or has an invalid type                                             |
| `200` with `"success": false` | The request was accepted, but a Flow node failed — inspect `error`, `node_results`, and `execution_id` |

When troubleshooting, record the HTTP status and full response body. Remove credentials and sensitive input data before sharing them.

## Migrating from the V1 endpoint

| V1                                  | V2                                                                                |
| ----------------------------------- | --------------------------------------------------------------------------------- |
| Endpoint: `/actions/execute/direct` | Endpoint: `/tools/execute-workflow`                                               |
| `flow_id`                           | `tool_id`                                                                         |
| `ui_form`                           | `inputs`                                                                          |
| Input definitions included          | Not included — plain runtime values only, keyed by the configured Flow input name |

<Note>
  The endpoint `/v2/actions/execute/direct` is for legacy Automator/Activepieces execution and should not be used to execute migrated V2 Flows.
</Note>

<Card title="Workflow V1 Migration Tool" icon="arrow-right-arrow-left" href="/tools/migrate-v1-workflows">
  Migrate an existing V1 workflow to V2 using the in-platform migration tool.
</Card>