> ## 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. # List workflows > List the workflows visible to your organization, newest first. `offset` in the response is the **next** page's start, not an echo of the one you sent. It is present whenever the page came back full, so page until a page returns fewer than `limit` rows. ## OpenAPI ````yaml /openapi_specs/workflows.json get /workflows 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. **Manage workflows** - create or update a version with `PUT /workflows/{workflowID}/versions/{versionID}` 2. **Trigger a public workflow** - POST to `/public/@{nickname}/workflows/{slug}/versions/{versionID}/trigger` with your inputs 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 execution detail response (`GET https://api.eachlabs.ai/v1/workflows/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://api.eachlabs.ai/v1 description: Production server security: - BearerAuth: [] tags: - name: Workflows description: Workflow and version management - name: Public Workflows description: Access public and unlisted workflows by organization nickname paths: /workflows: get: tags: - Workflows summary: List workflows description: > List the workflows visible to your organization, newest first. `offset` in the response is the **next** page's start, not an echo of the one you sent. It is present whenever the page came back full, so page until a page returns fewer than `limit` rows. operationId: listWorkflows parameters: - name: limit in: query required: false description: Page size. Defaults to 50, capped at 100. schema: type: integer default: 50 maximum: 100 - name: offset in: query required: false description: Page start. schema: type: integer default: 0 - name: category in: query required: false description: Keep only workflows carrying this category slug. schema: type: string example: image-generation - name: keyword in: query required: false description: Free-text match on the workflow name. schema: type: string - name: sort_key in: query required: false description: Sort column. Ignored unless `sort_direction` is also given. schema: type: string enum: - name - created_at - updated_at - trigger_count - status - name: sort_direction in: query required: false description: Sort direction. Ignored unless `sort_key` is also given. schema: type: string enum: - asc - desc - name: node_based in: query required: false description: Keep only workflows whose `node_based` flag matches. Omit for all. schema: type: boolean responses: '200': description: A page of workflows content: application/json: schema: $ref: '#/components/schemas/WorkflowList' '401': $ref: '#/components/responses/Unauthorized' components: schemas: WorkflowList: type: object description: A page of workflows properties: workflows: type: array items: $ref: '#/components/schemas/WorkflowSummary' offset: type: integer description: Start of the next page; present while pages come back full example: 50 total_count: type: integer description: Full result-set size for the applied filters example: 231 WorkflowSummary: type: object description: The list view of a workflow — summary fields only, without its versions 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 categories: type: array items: type: string description: Category slugs example: - image-generation tags: type: array items: type: string description: Free-form workflow tags example: - demo 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 clone_count: type: integer description: Number of times this workflow has been cloned example: 3 is_public: type: boolean description: Whether the workflow appears in public listings example: false production: type: boolean description: Whether this is a production workflow example: false node_based: type: boolean description: Whether the workflow's latest active version runs as a node graph example: false 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' Error: type: object required: - error properties: error: type: string description: Error message responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: 'API key passed as `Authorization: Bearer `' ````