> ## 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 with specified variables
## Endpoint
```
POST /workflows/{workflow_id}/{version}/initiate
```
## Authentication
This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:
```bash theme={null}
X-API-Key: ca_your_api_key_here
```
## 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 |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `user` | string | Email address of the user initiating the workflow. If not provided, workflow is attributed to the API key owner |
| `metadata` | object | Optional key-value pairs to attach to the task for tracking and filtering |
### 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`, `file_id` or `base64_content` | 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 three 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..."
}
```
## Request Example
```bash cURL theme={null}
curl -X POST "https://platform.chamelio.ai/workflows/vendor_contract_review/latest/initiate" \
-H "X-API-Key: ca_your_api_key_here" \
-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"
}
],
"user": "john.doe@example.com",
"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/workflows/{workflow_id}/{version}/initiate"
headers = {
"X-API-Key": "ca_your_api_key_here",
"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"
}
],
"user": "john.doe@example.com",
"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/workflows/${workflowId}/${version}/initiate`,
{
method: 'POST',
headers: {
'X-API-Key': 'ca_your_api_key_here',
'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'
}
],
user: 'john.doe@example.com',
metadata: {
source: 'vendor_portal'
}
})
}
);
const data = await response.json();
console.log(data);
```
## Response
### Success Response
**Status Code:** `200 OK`
```json theme={null}
{
"task_id": 12345,
"workflow_state_id": "wfs_abc123xyz",
"workflow_id": "vendor_contract_review",
"version": 1,
"status": "in_progress",
"message": "Workflow initiated successfully"
}
```
### Response Fields
| Field | Type | Description |
| ------------------- | ------- | --------------------------------------------------------------------- |
| `task_id` | integer | Unique identifier for the created task. Use this to track task status |
| `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 (typically `"in_progress"` or `"pending"`) |
| `message` | string | Success confirmation message |
## Error Responses
### 400 Bad Request
Returned when the version format is invalid or request structure is malformed.
```json theme={null}
{
"detail": "Invalid version format: invalid_version"
}
```
### 401 Unauthorized
Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.
```json theme={null}
{
"detail": "Invalid API key"
}
```
### 404 Not Found
Returned when the workflow or version doesn't exist.
```json theme={null}
{
"detail": "Workflow 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"
}
]
}
```
### 500 Internal Server Error
Returned when workflow initiation fails due to a server error.
```json theme={null}
{
"detail": "Failed to initiate workflow"
}
```
## Notes
Save the `task_id` from the response to track the workflow's progress using the [Get Task](/api-reference/endpoint/tasks/get) endpoint.
All required variables from the workflow schema must be provided in the `variables` array. Missing required variables will result in a 422 error.
Use the `metadata` field to add custom tracking information like source system, request ID, or priority level for filtering and reporting.
## Use Cases
This endpoint is useful for:
* **Automated workflow triggering** - Start workflows from external systems or events
* **Integration workflows** - Trigger Chamelio workflows from your applications
* **Bulk processing** - Initiate multiple workflow instances programmatically
* **User-initiated actions** - Allow end users to start workflows through custom interfaces