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

# Initiate Workflow

> Start a new workflow task instance as the access token's user

## Endpoint

```
POST /v2/workflows/{workflow_id}/{version}/initiate
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `workflows:write`

<Info>
  The task is created **as the access token's user**, who must be at least a requester on the workflow.
  The `user` field on the request body is ignored.
</Info>

## Path Parameters

| Parameter     | Type   | Required | Description                                                        |
| ------------- | ------ | -------- | ------------------------------------------------------------------ |
| `workflow_id` | string | Yes      | Unique identifier for the workflow                                 |
| `version`     | string | Yes      | Version number (e.g., "1") or "latest" for the most recent version |

## Request Body

The request body must be a JSON object with the following fields:

### Required Fields

| Field       | Type  | Description                                                              |
| ----------- | ----- | ------------------------------------------------------------------------ |
| `variables` | array | List of input values for workflow variables (see InputValue types below) |

### Optional Fields

| Field                              | Type    | Description                                                                                                                           |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `metadata`                         | object  | Key-value pairs (strings) to attach to the task for tracking and filtering                                                            |
| `auto_creation_of_extra_variables` | boolean | When `true`, `metadata` entries are passed as extra variables so the workflow can auto-create them. Defaults to `false`               |
| `extra_files`                      | array   | Files to attach to the task without mapping them to a workflow variable. Each entry is an object with `filename` and `base64_content` |
| `user`                             | string  | Ignored on this endpoint. The task is always attributed to the access token's user                                                    |

### InputValue Types

Each variable value must include `variable_id`, `type`, and `value`. The `type` determines the value format:

| Type             | Description           | Value Format                                                                           | Example                 |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------- | ----------------------- |
| `text`           | Text string           | string                                                                                 | `"Acme Corporation"`    |
| `number`         | Numeric value         | string (numeric)                                                                       | `"50000.00"`            |
| `boolean`        | True/false            | `"true"` or `"false"`                                                                  | `"true"`                |
| `date`           | Date                  | ISO 8601 format                                                                        | `"2025-01-15"`          |
| `email`          | Email address         | string (email)                                                                         | `"john@example.com"`    |
| `select`         | Dropdown selection    | string (option value)                                                                  | `"high_priority"`       |
| `file`           | File upload           | object with `value`, plus `file_id` or `base64_content`, and optional `file_extension` | See below               |
| `multiple_files` | Multiple file uploads | object with a `files` array                                                            | See below               |
| `user_entity`    | User reference        | string (email)                                                                         | `"manager@example.com"` |
| `business`       | Business entity       | string (name/identifier)                                                               | `"Legal Department"`    |

### File InputValue

For file inputs, you have two options:

**Option 1: Reference previously uploaded file**

```json theme={null}
{
  "variable_id": "contract_file",
  "type": "file",
  "value": "contract.pdf",
  "file_id": "doc_12345"
}
```

**Option 2: Include base64 content**

```json theme={null}
{
  "variable_id": "contract_file",
  "type": "file",
  "value": "contract.pdf",
  "file_extension": "pdf",
  "base64_content": "JVBERi0xLjQKJeLjz9MK..."
}
```

### Multiple Files InputValue

For variables that accept several files, use `type: "multiple_files"` and provide a `files` array. Each entry has the same shape as a single [File InputValue](#file-inputvalue) - `value` (the filename) plus either a `file_id` reference or `file_extension` + `base64_content`. You can mix references and uploads within the same array.

```json theme={null}
{
  "variable_id": "supporting_docs",
  "type": "multiple_files",
  "files": [
    {
      "value": "appendix_a.pdf",
      "file_id": "doc_123"
    },
    {
      "value": "appendix_b.pdf",
      "file_extension": "pdf",
      "base64_content": "JVBERi0xLjQKJeLjz9MK..."
    }
  ]
}
```

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.chamelio.ai/v2/workflows/vendor_contract_review/latest/initiate" \
    -H "Authorization: Bearer your_access_token" \
    -H "Content-Type: application/json" \
    -d '{
      "variables": [
        {
          "variable_id": "vendor_name",
          "type": "text",
          "value": "Acme Corporation"
        },
        {
          "variable_id": "contract_value",
          "type": "number",
          "value": "150000.00"
        },
        {
          "variable_id": "reviewer_email",
          "type": "email",
          "value": "legal@example.com"
        },
        {
          "variable_id": "contract_file",
          "type": "file",
          "value": "acme_contract.pdf",
          "file_id": "doc_789"
        },
        {
          "variable_id": "urgent",
          "type": "boolean",
          "value": "true"
        }
      ],
      "metadata": {
        "source": "vendor_portal",
        "priority": "high"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  workflow_id = "vendor_contract_review"
  version = "latest"

  url = f"https://platform.chamelio.ai/v2/workflows/{workflow_id}/{version}/initiate"
  headers = {
      "Authorization": "Bearer your_access_token",
      "Content-Type": "application/json"
  }

  payload = {
      "variables": [
          {
              "variable_id": "vendor_name",
              "type": "text",
              "value": "Acme Corporation"
          },
          {
              "variable_id": "contract_value",
              "type": "number",
              "value": "150000.00"
          },
          {
              "variable_id": "reviewer_email",
              "type": "email",
              "value": "legal@example.com"
          },
          {
              "variable_id": "contract_file",
              "type": "file",
              "value": "acme_contract.pdf",
              "file_id": "doc_789"
          }
      ],
      "metadata": {
          "source": "vendor_portal"
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const workflowId = 'vendor_contract_review';
  const version = 'latest';

  const response = await fetch(
    `https://platform.chamelio.ai/v2/workflows/${workflowId}/${version}/initiate`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your_access_token',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        variables: [
          {
            variable_id: 'vendor_name',
            type: 'text',
            value: 'Acme Corporation'
          },
          {
            variable_id: 'contract_value',
            type: 'number',
            value: '150000.00'
          },
          {
            variable_id: 'reviewer_email',
            type: 'email',
            value: 'legal@example.com'
          },
          {
            variable_id: 'contract_file',
            type: 'file',
            value: 'acme_contract.pdf',
            file_id: 'doc_789'
          }
        ],
        metadata: {
          source: 'vendor_portal'
        }
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "task_id": 12345,
  "task_url": "https://app.chamelio.ai/b/workflows/tasks/12345",
  "workflow_state_id": "wfs_abc123xyz",
  "workflow_id": "vendor_contract_review",
  "version": 1,
  "status": "pending",
  "message": "Workflow initiated successfully"
}
```

### Response Fields

| Field               | Type            | Description                                                                   |
| ------------------- | --------------- | ----------------------------------------------------------------------------- |
| `task_id`           | integer or null | Unique identifier for the created task. Use this to track task status         |
| `task_url`          | string or null  | Link to the created task in the Chamelio app. `null` when no task was created |
| `workflow_state_id` | string          | Internal workflow state identifier                                            |
| `workflow_id`       | string          | Workflow identifier that was initiated                                        |
| `version`           | integer         | Workflow version number that was used                                         |
| `status`            | string          | Initial task status                                                           |
| `message`           | string          | Success confirmation message                                                  |

## Error Responses

### 400 Bad Request

Returned when the version format is invalid, or when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.

```json theme={null}
{
  "detail": "Invalid version format: invalid_version"
}
```

```json theme={null}
{
  "detail": "client_credentials tokens are not associated with a user"
}
```

### 401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token lacks the required scope:

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: workflows:write"
}
```

Or when the user is not permitted to request this workflow:

```json theme={null}
{
  "detail": "You do not have access to this resource"
}
```

### 404 Not Found

Returned when the workflow or version does not exist.

```json theme={null}
{
  "detail": "Not found"
}
```

### 422 Validation Error

Returned when the request body is invalid or variables don't match the workflow schema.

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "variables", 0, "value"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### 429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 500 Internal Server Error

Returned when workflow initiation fails due to a server error.

```json theme={null}
{
  "detail": "Failed to initiate workflow"
}
```

## Notes

<Info>
  Save the `task_id` from the response to track the workflow's progress using the
  [Get Task](/api-reference/endpoint/v2/tasks/get) endpoint, or hand `task_url` to the user to open the
  task in Chamelio.
</Info>

<Warning>
  The access token's user must be at least a requester on the workflow. If they are not, the request
  returns `403` - you cannot initiate on behalf of someone else here.
</Warning>

<Warning>
  All required variables from the workflow schema must be provided in the `variables` array. Missing
  required variables result in a 422 error.
</Warning>

<Tip>
  Use the `metadata` field to add custom tracking information like source system, request ID, or
  priority level for filtering and reporting.
</Tip>

## Use Cases

This endpoint is useful for:

* **User-initiated actions** - Let a user start a workflow from your own interface, as themselves
* **Integration workflows** - Trigger Chamelio workflows from your applications
* **Correct attribution** - Ensure the requester recorded on the task is the real person
* **Permission-safe automation** - Rely on Chamelio to reject workflows the user may not request