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

​
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
attributesarrayList of simple key-value pairs for workflow variables (see below)

​
Optional Fields

FieldTypeDescription
filesarrayList of files with base64 content (see File Format below)
userstringEmail address of the user initiating the workflow. If not provided, workflow is attributed to the API key owner
metadataobjectOptional key-value pairs (accepted but currently ignored)

​
Attribute Format

Each attribute is a simple object with key and value fields: 
{
  "key": "vendor_name",
  "value": "Acme Corporation"
}
The system will match attributes to workflow variables using flexible matching:
  1. Exact match by variable ID
  2. Case-insensitive match by variable title
  3. Normalized match (lowercase, spaces/underscores/hyphens ignored)
All values are provided as strings. The system will automatically convert them to the appropriate type based on the workflow schema.

​
File Format

Files are provided separately from attributes: 
{
  "filename": "contract.pdf",
  "base64_content": "JVBERi0xLjQKJeLjz9MK..."
}
Files are matched to file-type workflow fields by order. Ensure files in the array correspond to the order of file fields in your workflow.

​
When to Use This Endpoint

This endpoint is designed for scenarios where the integrating system or user cannot maintain variable-specific mapping and control. Use this endpoint when:
  • Generic integration systems that handle multiple workflows without custom configuration for each
  • Low-code/no-code platforms where users configure integrations through UI without coding
  • Form builders that generate dynamic field mappings based on workflow schemas
  • Third-party tools that need to integrate with workflows but can’t be customized for each workflow’s schema
  • Rapid prototyping where you want to test workflows without setting up precise type mappings
  • Simple scripts where maintaining detailed variable schemas adds unnecessary complexity
The flexible matching (by ID, title, or normalized name) means integrating systems can use human-readable labels without knowing the exact internal variable IDs.
If your integration requires precise control over variable types, file references, or needs to distinguish between fields with similar names, use the standard Initiate Workflow endpoint instead.

​
Request Example

curl -X POST "https://platform.chamelio.ai/workflows/vendor_contract_review/latest/initiate-flexible" \
  -H "X-API-Key: ca_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": [
      {
        "key": "vendor_name",
        "value": "Acme Corporation"
      },
      {
        "key": "contract_value",
        "value": "150000.00"
      },
      {
        "key": "reviewer_email",
        "value": "legal@example.com"
      },
      {
        "key": "urgent",
        "value": "true"
      }
    ],
    "files": [
      {
        "filename": "acme_contract.pdf",
        "base64_content": "JVBERi0xLjQKJeLjz9MK..."
      }
    ],
    "user": "john.doe@example.com"
  }'

​
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, request structure is malformed, or attribute matching fails. 
{
  "detail": "Could not match attribute 'invalid_key' to any workflow variable"
}

​
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 required variables are missing. 
{
  "detail": [
    {
      "loc": ["body", "attributes"],
      "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"
}

​
Comparison with /initiate

Aspect/initiate/initiate-flexible
Input formatTyped InputValue objectsSimple {key, value} pairs
Variable matchingExact variable_id onlyFlexible: ID → title → normalized
File handlingRequires file_id or typed objectBase64 content, matched by order
Type specificationExplicit type field requiredAuto-detected from schema
Use casePrecise control, file referencesSystems without variable-specific mapping

​
Notes

Save the task_id from the response to track the workflow’s progress using the Get Task endpoint.
Use flexible attribute keys: “Vendor Name”, “vendor_name”, and “vendor-name” will all match the same variable.
Files in the files array are matched to workflow file fields by position. The first file in the array is assigned to the first file field in the workflow, and so on.

​
Use Cases

This flexible endpoint is ideal for:
  • Generic integration platforms - iPaaS solutions (Zapier, Make, Workato) that connect to multiple workflows without per-workflow configuration
  • Form builders - Dynamic forms that adapt to workflow schemas without hardcoded field mappings
  • No-code tools - Platforms where users configure integrations visually without access to variable IDs
  • Multi-tenant systems - Applications serving multiple organizations with different workflow schemas
  • API aggregators - Services that normalize data from various sources before initiating workflows
  • Rapid prototyping - Quick testing without setting up precise variable mappings
  • Simple scripts - Automation where maintaining detailed schemas is unnecessary overhead
Key advantage: Integrating systems don’t need to maintain a mapping table between their field names and Chamelio’s internal variable IDs. They can use human-readable labels directly. For precise control over variable types, file references, or when you need to distinguish between similarly-named fields, use the standard Initiate Workflow endpoint.