> ## Documentation Index > Fetch the complete documentation index at: https://docs.eachlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Trigger workflow > Start an execution of the workflow. By default, this triggers the latest version of the workflow. You can optionally specify a version_id in the request body to trigger a specific version. The workflow is executed asynchronously - you'll receive an execution ID immediately, then poll `/executions/{executionID}` to check status and retrieve results. ## OpenAPI ````yaml /openapi_specs/workflows.json post /{workflowID}/trigger openapi: 3.0.3 info: title: Workflows Engine API description: > # Workflows Engine API Execute and monitor AI workflows with a simple, consistent API. ## Quick Start 1. **Trigger a workflow** - POST to `/{workflowID}/trigger` with your inputs 2. **Monitor execution** - GET `/executions/{executionID}` to check status 3. **Optional**: Provide a `webhook_url` to receive automatic notifications when complete --- ## Webhook Notifications When you provide a `webhook_url` when triggering a workflow, the Workflows Engine will automatically **POST** to your endpoint with the execution results when the workflow completes (successfully or with an error). ### Key Features - ✅ **Consistent Payload**: The webhook payload has the same structure as the response from `GET /executions/{executionID}` - ✅ **Automatic Retries**: Failed webhook deliveries are automatically retried with exponential backoff - ✅ **Simple Integration**: No authentication required - your endpoint just needs to accept POST requests ### Webhook Request The engine will POST to your `webhook_url` with: - **Method**: `POST` - **Content-Type**: `application/json` - **Body**: Execution details (see payload structure below) ### Example Webhook Payload ```json { "execution_id": "69ae8c7b-7500-4a45-b7c0-348b8cc2665b", "workflow_id": "50741f40-8621-4d46-8a91-dff4d873be98", "status": "completed", "started_at": "2025-12-04T11:48:10Z", "inputs": { "story": "tell an epic story of a rat graduating from law" }, "step_outputs": { "step1": { "step_id": "step1", "status": "completed", "output": "Once upon a time in Ratropolis...", "primary": "Once upon a time in Ratropolis...", "metadata": { "model": "openai-chatgpt-5", "version": "0.0.1", "params": { "system_prompt": "You are a helpful assistant", "max_output_tokens": 512 } } }, "step2": { "step_id": "step2", "status": "completed", "output": [ "https://storage.googleapis.com/uploads/image1.png", "https://storage.googleapis.com/uploads/image2.png" ], "primary": "https://storage.googleapis.com/uploads/image1.png", "metadata": { "model": "nano-banana-pro", "params": { "num_images": 2, "aspect_ratio": "16:9" } } } }, "output": [ "https://storage.googleapis.com/uploads/image1.png", "https://storage.googleapis.com/uploads/image2.png" ] } ``` ### Example Webhook Handler ```python @app.post("/webhooks/workflow-completed") async def handle_workflow_webhook(request: Request): execution = await request.json() if execution["status"] == "completed": # Process successful execution final_output = execution["output"] step_details = execution["step_outputs"] print(f"Workflow completed: {final_output}") elif execution["status"] == "failed": # Handle failure error = execution.get("error_cause", "Unknown error") print(f"Workflow failed: {error}") return {"received": True} ``` Your webhook endpoint should return a `200 OK` status to acknowledge receipt. --- ## Fallback Configuration Model steps support an optional **fallback configuration** that automatically retries with an alternative model if the primary model invocation fails. This provides resilience against temporary model outages or rate limits. ### How Fallback Works When a model step has fallback configured, the workflow engine will: 1. **Execute the primary model** with its configured parameters 2. **If the primary attempt fails**, automatically execute the fallback model configuration 3. **Mark the step as failed only if both primary and fallback attempts fail** ### Fallback Configuration Add a `fallback` object to any model step in your workflow definition: ```json { "step_id": "generate_image", "type": "model", "model": "flux-dev", "params": { "prompt": "{{inputs.prompt}}", "num_images": 1 }, "fallback": { "enabled": true, "model": "flux-1-1-pro", "params": { "prompt": "{{inputs.prompt}}", "guidance_scale": 7.5 } } } ``` ### Fallback Properties | Property | Type | Description | |----------|------|-------------| | `enabled` | boolean | Enable or disable fallback for this step (default: `true`) | | `model` | string | Alternative AI model identifier to use on failure | | `version` | string | Fallback model version (defaults to primary version when omitted) | | `params` | object | Model-specific parameters for the fallback (supports template variables) | ### Detecting Fallback Usage When a fallback is used, the step's metadata in execution results will include: - `fallback_used: true` - Indicates the step completed using the fallback configuration - `primary_error` - Human-readable description of why the primary attempt failed ### Example Execution Response with Fallback ```json { "step_id": "generate_image", "status": "completed", "output": "https://storage.googleapis.com/uploads/image.png", "metadata": { "model": "flux-1-1-pro", "fallback_used": true, "primary_error": "Primary model flux-dev failed: rate limit exceeded" } } ``` --- ## Unlisted Workflows Versions can be "unlisted" - accessible via direct link but hidden from public listings. **Visibility states:** - **Private** (default): Organization only - **Unlisted**: Accessible via link, hidden from public listings - **Public**: Visible in listings and accessible to everyone **Setting unlisted:** Use `allowed_to_share: true` when creating or updating a version. ```bash # Create unlisted version PUT /workflows/{workflowID}/versions/v1 { "allowed_to_share": true, ... } ``` **Behavior:** - `allowed_to_share: true` → Creates/updates as unlisted - `allowed_to_share: false` → Creates/updates as private - No effect on public versions (never downgraded) version: 1.0.0 x-logo: url: ./logo-white.svg altText: Eachlabs Logo servers: - url: https://workflows.eachlabs.run/api/v1 description: >- Deprecated compatibility production host. This public URL remains supported for now, but will soon move under the api-service host at https://api.eachlabs.ai. security: - ApiKeyAuth: [] tags: - name: Categories description: Workflow categories for organization - name: Workflows description: Workflow and version management - name: Executions description: Workflow execution and monitoring - name: Public Workflows description: Access public and unlisted workflows by organization nickname paths: /{workflowID}/trigger: parameters: - name: workflowID in: path required: true description: Unique workflow identifier schema: type: string example: wf_abc123 post: tags: - Executions summary: Trigger workflow description: > Start an execution of the workflow. By default, this triggers the latest version of the workflow. You can optionally specify a version_id in the request body to trigger a specific version. The workflow is executed asynchronously - you'll receive an execution ID immediately, then poll `/executions/{executionID}` to check status and retrieve results. operationId: triggerWorkflow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TriggerWorkflowRequest' responses: '202': description: Workflow execution started content: application/json: schema: $ref: '#/components/schemas/ExecutionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: schemas: TriggerWorkflowRequest: type: object properties: version_id: type: string description: > **Optional**: Specific version to trigger. If not provided, triggers the latest version of the workflow. This allows you to execute specific versions for testing or comparison. example: v1 inputs: type: object description: Input parameters defined in the workflow definition for the workflow example: text: tell me a story webhook_url: type: string format: uri description: > **Optional webhook URL for execution completion notifications.** When provided, the engine will POST an `ExecutionDetails` payload to this URL when the workflow finishes (either successfully or with an error). See the **Webhooks** section for detailed information about webhook behavior and payload structure. example: https://your-api.com/webhooks/workflow-completed ExecutionResponse: type: object description: Response from triggering a workflow execution properties: execution_id: type: string description: Unique execution identifier (only present for successful triggers) example: exec_xyz789 status: type: string enum: - queued - failed description: > Execution status immediately after triggering. - `queued`: Workflow execution has been queued and will start shortly - `failed`: Trigger failed due to validation or system error example: queued started_at: type: string format: date-time description: >- RFC3339 timestamp when the execution was queued (only present for successful triggers) message: type: string description: Error message (only present when status is "failed") example: 'invalid input: missing required field' example: execution_id: e2dba2bb-bc1d-4651-b6bf-fbbbebdee104 status: queued started_at: '2025-12-03T10:21:09Z' Error: type: object required: - error properties: error: type: string description: Error message responses: BadRequest: description: Bad request - Invalid input content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found - Resource does not exist content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````