Skip to main content

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.

​
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

ParameterTypeRequiredDescription
workflow_idstringYesUnique identifier for the workflow
versionstringYesVersion 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

FieldTypeDescription
variablesarrayList of input values for workflow variables (see InputValue types below)

​
Optional Fields

FieldTypeDescription
userstringEmail address of the user initiating the workflow. If not provided, workflow is attributed to the API key owner
metadataobjectOptional 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:
TypeDescriptionValue FormatExample
textText stringstring"Acme Corporation"
numberNumeric valuestring (numeric)"50000.00"
booleanTrue/false"true" or "false""true"
dateDateISO 8601 format"2025-01-15"
emailEmail addressstring (email)"john@example.com"
selectDropdown selectionstring (option value)"high_priority"
fileFile uploadobject with value, file_id or base64_contentSee below
user_entityUser referencestring (email)"manager@example.com"
businessBusiness entitystring (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..."
}

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

​
Response

​
Success Response

Status Code: 200 OK 
{
  "task_id": 12345,
  "workflow_state_id": "wfs_abc123xyz",
  "workflow_id": "vendor_contract_review",
  "version": 1,
  "status": "in_progress",
  "message": "Workflow initiated successfully"
}

​
Response Fields

FieldTypeDescription
task_idintegerUnique identifier for the created task. Use this to track task status
workflow_state_idstringInternal workflow state identifier
workflow_idstringWorkflow identifier that was initiated
versionintegerWorkflow version number that was used
statusstringInitial task status (typically "in_progress" or "pending")
messagestringSuccess 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