Initiate Workflow

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:

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	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`

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 three options: Option 1: Reference previously uploaded file

{
  "variable_id": "contract_file",
  "type": "file",
  "value": "contract.pdf",
  "file_id": "doc_12345"
}

Option 2: Include base64 content

{
  "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 - value (the filename) plus either a file_id reference or file_extension + base64_content. You can mix references and uploads within the same array.

{
  "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

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"
    }
  }'

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

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

{
  "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": "in_progress",
  "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 (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.

{
  "detail": "Invalid version format: invalid_version"
}

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.

{
  "detail": "Invalid API key"
}

404 Not Found

Returned when the workflow or version doesn’t exist.

{
  "detail": "Workflow not found"
}

422 Validation Error

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

{
  "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.

{
  "detail": "Failed to initiate workflow"
}

Notes

Save the task_id from the response to track the workflow’s progress using the Get Task 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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

InputValue Types

File InputValue

Multiple Files InputValue

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

422 Validation Error

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Required Fields

​Optional Fields

​InputValue Types

​File InputValue

​Multiple Files InputValue

​Request Example

​Response

​Success Response

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​404 Not Found

​422 Validation Error

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

InputValue Types

File InputValue

Multiple Files InputValue

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

422 Validation Error

500 Internal Server Error

Notes

Use Cases