> ## 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. # Update workflow > Update workflow metadata such as name, description, categories, and visibility. Note: To update the workflow definition (steps), use the version endpoints instead. Locked workflows cannot be modified unless you're unlocking them. ## OpenAPI ````yaml /openapi_specs/workflows.json put /workflows/{workflowID} 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: /workflows/{workflowID}: parameters: - $ref: '#/components/parameters/WorkflowID' put: tags: - Workflows summary: Update workflow description: > Update workflow metadata such as name, description, categories, and visibility. Note: To update the workflow definition (steps), use the version endpoints instead. Locked workflows cannot be modified unless you're unlocking them. operationId: updateWorkflow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWorkflowRequest' responses: '200': description: Workflow updated successfully content: application/json: schema: $ref: '#/components/schemas/WorkflowDetail' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: WorkflowID: name: workflowID in: path required: true description: Unique workflow identifier schema: type: string example: wf_abc123 schemas: UpdateWorkflowRequest: type: object description: > Update workflow metadata. All fields are optional - only provided fields will be updated. Note: To update the workflow definition (steps), use the version endpoints instead. properties: name: type: string description: Human-readable workflow name example: Text to Image Generator v2 description: type: string description: Detailed description of what the workflow does example: Enhanced image generation with multiple models categories: type: array items: type: string description: List of category slugs example: - image-generation - ai - production locked: type: boolean description: Lock/unlock the workflow from modifications production: type: boolean description: Mark as production workflow WorkflowDetail: type: object description: Complete workflow information including all versions required: - workflow_id - name - description properties: workflow_id: type: string format: uuid description: Unique workflow identifier example: 50741f40-8621-4d46-8a91-dff4d873be98 slug: type: string description: URL-friendly workflow identifier example: text-to-image-generator name: type: string description: Human-readable workflow name example: Text to Image Generator description: type: string description: Workflow description example: Generates images from text prompts categories: type: array items: type: string description: Category slugs example: - image-generation - ai locked: type: boolean description: Whether workflow is locked example: false production: type: boolean description: Whether this is a production workflow example: false latest_version_id: type: string description: Most recently updated version ID example: v2 status: type: string enum: - active - archived - deleted description: Workflow lifecycle status example: active trigger_count: type: integer description: Total number of times this workflow has been triggered example: 42 created_at: type: string format: date-time description: RFC3339 timestamp when workflow was created example: '2025-12-01T10:00:00Z' updated_at: type: string format: date-time description: RFC3339 timestamp when workflow was last updated example: '2025-12-07T15:30:00Z' versions: type: array description: List of all versions for this workflow items: $ref: '#/components/schemas/WorkflowVersionSummary' WorkflowVersionSummary: type: object description: Summary information about a workflow version required: - version_id - slug properties: version_id: type: string description: Version identifier example: v1 slug: type: string description: Workflow slug (inherited from parent workflow) example: text-to-image-generator locked: type: boolean description: Whether this version is locked from modifications example: false production: type: boolean description: Whether this is a production version example: true allowed_to_share: type: boolean description: >- True if version is unlisted (accessible via direct link but hidden from public listings). example: false trigger_count: type: integer description: Number of times this specific version has been triggered example: 15 created_at: type: string format: date-time description: RFC3339 timestamp when version was created example: '2025-12-01T10:00:00Z' updated_at: type: string format: date-time description: RFC3339 timestamp when version was last updated example: '2025-12-05T14:20:00Z' status: type: string enum: - active - archived - deleted description: Version lifecycle status example: active definition: type: object description: > The complete workflow definition (only included in detail responses). Contains steps, input schema, and metadata. 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' Forbidden: description: Forbidden - Operation not allowed (e.g., workflow is locked) 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 ````