Workflows Endpoints¶
Multi-step orchestrated pipeline management.
Overview¶
| Method | Endpoint | Description |
|---|---|---|
| POST | /workflows/ |
Create workflow |
| GET | /workflows/{workflow_id} |
Get workflow status |
| POST | /workflows/{workflow_id}/start |
Start workflow |
| POST | /workflows/{workflow_id}/resume |
Resume paused workflow |
| POST | /workflows/{workflow_id}/cleanup |
Cleanup resources |
Workflow Lifecycle¶
stateDiagram-v2
[*] --> Created: Create
Created --> Running: Start
Running --> Paused: Pause
Paused --> Running: Resume
Running --> Completed: All steps done
Running --> Failed: Step fails
Completed --> [*]
Failed --> [*]API Reference¶
Custom API - Workflows 1.0.0¶
This is a very custom OpenAPI schema
workflows¶
POST /api/v1/workflows/¶
Create Workflow
Description
Create a new workflow.
Creates a workflow from the provided definition. If start=True (default),
the workflow will be started immediately after creation.
The workflow definition must include: - name: Human-readable name - steps: List of step definitions forming a DAG - origin_instance: Identifier for the calling system
Each step must specify: - id: Unique identifier within the workflow - task_type: Type of task (GENERATION, REFINE, etc.) - config: Task-specific configuration - depends_on: (optional) List of step IDs this step depends on - input_mappings: (optional) How to map outputs from previous steps
Returns the created workflow with all steps.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
start |
query | boolean | True | No | Start workflow immediately after creation |
Request body
{
"description": "Generate and refine fashion images",
"name": "Fashion Image Pipeline",
"origin_instance": "api-prod",
"steps": [
{
"config": {
"height": 1024,
"prompt": "fashion model wearing elegant dress",
"width": 1024
},
"id": "generate",
"task_type": "GENERATION"
},
{
"config": {
"upscale_factor": 2.0
},
"depends_on": [
"generate"
],
"id": "refine",
"input_mappings": [
{
"from_field": "result_image_path",
"from_step": "generate",
"to_field": "base_image_url"
}
],
"task_type": "REFINE"
}
]
}
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Name",
"description": "Human-readable workflow name"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"type": "null"
}
],
"title": "Description",
"description": "Optional workflow description"
},
"steps": {
"items": {
"$ref": "#/components/schemas/WorkflowStepDefinition"
},
"type": "array",
"minItems": 1,
"title": "Steps",
"description": "List of steps defining the workflow DAG"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config",
"description": "Global workflow configuration"
},
"origin_instance": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"title": "Origin Instance",
"description": "Origin instance identifier"
},
"origin_zone": {
"anyOf": [
{
"type": "string",
"maxLength": 50
},
{
"type": "null"
}
],
"title": "Origin Zone",
"description": "Origin zone identifier"
},
"origin_tenant_id": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"title": "Origin Tenant Id",
"description": "Tenant identifier for multi-tenant setups"
},
"origin_reference": {
"anyOf": [
{
"type": "string",
"maxLength": 512
},
{
"type": "null"
}
],
"title": "Origin Reference",
"description": "External reference ID for tracking"
},
"webhook_url": {
"anyOf": [
{
"type": "string",
"maxLength": 512
},
{
"type": "null"
}
],
"title": "Webhook Url",
"description": "URL to call when workflow completes"
},
"suppress_subtask_events": {
"type": "boolean",
"title": "Suppress Subtask Events",
"description": "Whether to suppress individual task events",
"default": true
}
},
"type": "object",
"required": [
"name",
"steps",
"origin_instance"
],
"title": "CreateWorkflow",
"description": "Schema for creating a new workflow.",
"example": {
"description": "Generate and refine fashion images",
"name": "Fashion Image Pipeline",
"origin_instance": "api-prod",
"steps": [
{
"config": {
"height": 1024,
"prompt": "fashion model wearing elegant dress",
"width": 1024
},
"id": "generate",
"task_type": "GENERATION"
},
{
"config": {
"upscale_factor": 2.0
},
"depends_on": [
"generate"
],
"id": "refine",
"input_mappings": [
{
"from_field": "result_image_path",
"from_step": "generate",
"to_field": "base_image_url"
}
],
"task_type": "REFINE"
}
]
}
}
Responses
{
"id": "6c2b2377-1491-4cdc-80f0-70bebb0dbe92",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "357a030f-534a-4bfe-aeaf-bfd4c5e7a92c",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"status": {
"$ref": "#/components/schemas/WorkflowStatus"
},
"total_steps": {
"type": "integer",
"title": "Total Steps"
},
"completed_steps": {
"type": "integer",
"title": "Completed Steps"
},
"progress": {
"type": "number",
"title": "Progress"
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Step"
},
"final_step_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Final Step Id"
},
"final_step_result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Final Step Result"
},
"canvas_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Canvas Task Id"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"suppress_subtask_events": {
"type": "boolean",
"title": "Suppress Subtask Events"
},
"origin_instance": {
"type": "string",
"title": "Origin Instance"
},
"origin_zone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Zone"
},
"origin_tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Tenant Id"
},
"origin_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Reference"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"errors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Errors"
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
},
"is_deleted": {
"type": "boolean",
"title": "Is Deleted",
"default": false
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
},
"steps": {
"items": {
"$ref": "#/components/schemas/WorkflowStepPublic"
},
"type": "array",
"title": "Steps"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"total_steps",
"completed_steps",
"progress",
"config",
"suppress_subtask_events",
"origin_instance",
"errors",
"created_at",
"updated_at"
],
"title": "WorkflowPublic",
"description": "Public representation of a workflow."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
GET /api/v1/workflows/¶
List Workflows
Description
List workflows with filtering and pagination.
Supports filtering by: - status: Filter by workflow status - origin_instance: Filter by origin system - origin_tenant_id: Filter by tenant - include_deleted: Include soft-deleted workflows (default: False)
Results are ordered by creation date (newest first).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
include_deleted |
query | boolean | False | No | Include deleted workflows |
limit |
query | integer | 50 | No | |
origin_instance |
query | No | |||
origin_tenant_id |
query | No | |||
skip |
query | integer | 0 | No | |
status |
query | No |
Responses
{
"workflows": [
{
"id": "215012b8-73ac-4988-83ab-abea0f197c94",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "b7aeaca5-8168-4fc3-b545-506084bfdfc4",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
}
],
"total": 0,
"skip": 0,
"limit": 0
}
Schema of the response body
{
"properties": {
"workflows": {
"items": {
"$ref": "#/components/schemas/WorkflowPublic"
},
"type": "array",
"title": "Workflows"
},
"total": {
"type": "integer",
"title": "Total"
},
"skip": {
"type": "integer",
"title": "Skip"
},
"limit": {
"type": "integer",
"title": "Limit"
}
},
"type": "object",
"required": [
"workflows",
"total",
"skip",
"limit"
],
"title": "WorkflowListResponse",
"description": "Response schema for listing workflows."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
GET /api/v1/workflows/{workflow_id}¶
Get Workflow
Description
Get a workflow by ID.
Returns the workflow with all its steps and their current status.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
workflow_id |
path | string | No |
Responses
{
"id": "edff48b9-8cfc-45ca-b4f9-e8ce5d038aeb",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "b6d2c219-5b7e-4d96-8975-5ce085ce991d",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"status": {
"$ref": "#/components/schemas/WorkflowStatus"
},
"total_steps": {
"type": "integer",
"title": "Total Steps"
},
"completed_steps": {
"type": "integer",
"title": "Completed Steps"
},
"progress": {
"type": "number",
"title": "Progress"
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Step"
},
"final_step_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Final Step Id"
},
"final_step_result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Final Step Result"
},
"canvas_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Canvas Task Id"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"suppress_subtask_events": {
"type": "boolean",
"title": "Suppress Subtask Events"
},
"origin_instance": {
"type": "string",
"title": "Origin Instance"
},
"origin_zone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Zone"
},
"origin_tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Tenant Id"
},
"origin_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Reference"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"errors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Errors"
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
},
"is_deleted": {
"type": "boolean",
"title": "Is Deleted",
"default": false
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
},
"steps": {
"items": {
"$ref": "#/components/schemas/WorkflowStepPublic"
},
"type": "array",
"title": "Steps"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"total_steps",
"completed_steps",
"progress",
"config",
"suppress_subtask_events",
"origin_instance",
"errors",
"created_at",
"updated_at"
],
"title": "WorkflowPublic",
"description": "Public representation of a workflow."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
PATCH /api/v1/workflows/{workflow_id}¶
Update Workflow
Description
Update workflow metadata.
Can update: - name - description - webhook_url
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
workflow_id |
path | string | No |
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the request body
{
"properties": {
"name": {
"anyOf": [
{
"type": "string",
"maxLength": 255,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"type": "null"
}
],
"title": "Description"
},
"webhook_url": {
"anyOf": [
{
"type": "string",
"maxLength": 512
},
{
"type": "null"
}
],
"title": "Webhook Url"
}
},
"type": "object",
"title": "WorkflowUpdate",
"description": "Schema for updating a workflow."
}
Responses
{
"id": "ff8e2807-357e-4b00-836e-f031a1c24f7a",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "9ce65fdb-00cb-44ba-b085-e420a37c5880",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"status": {
"$ref": "#/components/schemas/WorkflowStatus"
},
"total_steps": {
"type": "integer",
"title": "Total Steps"
},
"completed_steps": {
"type": "integer",
"title": "Completed Steps"
},
"progress": {
"type": "number",
"title": "Progress"
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Step"
},
"final_step_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Final Step Id"
},
"final_step_result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Final Step Result"
},
"canvas_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Canvas Task Id"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"suppress_subtask_events": {
"type": "boolean",
"title": "Suppress Subtask Events"
},
"origin_instance": {
"type": "string",
"title": "Origin Instance"
},
"origin_zone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Zone"
},
"origin_tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Tenant Id"
},
"origin_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Reference"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"errors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Errors"
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
},
"is_deleted": {
"type": "boolean",
"title": "Is Deleted",
"default": false
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
},
"steps": {
"items": {
"$ref": "#/components/schemas/WorkflowStepPublic"
},
"type": "array",
"title": "Steps"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"total_steps",
"completed_steps",
"progress",
"config",
"suppress_subtask_events",
"origin_instance",
"errors",
"created_at",
"updated_at"
],
"title": "WorkflowPublic",
"description": "Public representation of a workflow."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
DELETE /api/v1/workflows/{workflow_id}¶
Cancel Workflow
Description
Cancel a running workflow.
Cancels the workflow and all running tasks. The workflow must be in PENDING or RUNNING state.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
workflow_id |
path | string | No |
Responses
{
"id": "a134125e-6de2-48bc-a82d-5638f47291bb",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "d41c9d6b-a7b3-4322-8dce-830b33c98e5c",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"status": {
"$ref": "#/components/schemas/WorkflowStatus"
},
"total_steps": {
"type": "integer",
"title": "Total Steps"
},
"completed_steps": {
"type": "integer",
"title": "Completed Steps"
},
"progress": {
"type": "number",
"title": "Progress"
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Step"
},
"final_step_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Final Step Id"
},
"final_step_result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Final Step Result"
},
"canvas_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Canvas Task Id"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"suppress_subtask_events": {
"type": "boolean",
"title": "Suppress Subtask Events"
},
"origin_instance": {
"type": "string",
"title": "Origin Instance"
},
"origin_zone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Zone"
},
"origin_tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Tenant Id"
},
"origin_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Reference"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"errors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Errors"
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
},
"is_deleted": {
"type": "boolean",
"title": "Is Deleted",
"default": false
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
},
"steps": {
"items": {
"$ref": "#/components/schemas/WorkflowStepPublic"
},
"type": "array",
"title": "Steps"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"total_steps",
"completed_steps",
"progress",
"config",
"suppress_subtask_events",
"origin_instance",
"errors",
"created_at",
"updated_at"
],
"title": "WorkflowPublic",
"description": "Public representation of a workflow."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
POST /api/v1/workflows/{workflow_id}/start¶
Start Workflow
Description
Start a pending workflow.
The workflow must be in PENDING state. This compiles the workflow DAG into Celery tasks and begins execution.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
workflow_id |
path | string | No |
Responses
{
"id": "8d03dedb-bb50-4cea-bd25-369853e7d5aa",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "60e40c2c-74e3-4826-84c7-1bcb3472bd91",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"status": {
"$ref": "#/components/schemas/WorkflowStatus"
},
"total_steps": {
"type": "integer",
"title": "Total Steps"
},
"completed_steps": {
"type": "integer",
"title": "Completed Steps"
},
"progress": {
"type": "number",
"title": "Progress"
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Step"
},
"final_step_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Final Step Id"
},
"final_step_result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Final Step Result"
},
"canvas_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Canvas Task Id"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"suppress_subtask_events": {
"type": "boolean",
"title": "Suppress Subtask Events"
},
"origin_instance": {
"type": "string",
"title": "Origin Instance"
},
"origin_zone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Zone"
},
"origin_tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Tenant Id"
},
"origin_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Reference"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"errors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Errors"
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
},
"is_deleted": {
"type": "boolean",
"title": "Is Deleted",
"default": false
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
},
"steps": {
"items": {
"$ref": "#/components/schemas/WorkflowStepPublic"
},
"type": "array",
"title": "Steps"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"total_steps",
"completed_steps",
"progress",
"config",
"suppress_subtask_events",
"origin_instance",
"errors",
"created_at",
"updated_at"
],
"title": "WorkflowPublic",
"description": "Public representation of a workflow."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
POST /api/v1/workflows/{workflow_id}/resume¶
Resume Workflow
Description
Resume a failed workflow from its last checkpoint.
Only works for workflows in FAILED or PAUSED state. Resets failed/running steps and recompiles the remaining DAG for execution.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
workflow_id |
path | string | No |
Responses
{
"id": "fd2c0974-a0e6-4ab7-9236-a1bb92df8e3c",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "6b1b05e4-ad85-4652-94e8-7864da1ecfa4",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"status": {
"$ref": "#/components/schemas/WorkflowStatus"
},
"total_steps": {
"type": "integer",
"title": "Total Steps"
},
"completed_steps": {
"type": "integer",
"title": "Completed Steps"
},
"progress": {
"type": "number",
"title": "Progress"
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Step"
},
"final_step_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Final Step Id"
},
"final_step_result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Final Step Result"
},
"canvas_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Canvas Task Id"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"suppress_subtask_events": {
"type": "boolean",
"title": "Suppress Subtask Events"
},
"origin_instance": {
"type": "string",
"title": "Origin Instance"
},
"origin_zone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Zone"
},
"origin_tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Tenant Id"
},
"origin_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Origin Reference"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"errors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Errors"
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
},
"is_deleted": {
"type": "boolean",
"title": "Is Deleted",
"default": false
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
},
"steps": {
"items": {
"$ref": "#/components/schemas/WorkflowStepPublic"
},
"type": "array",
"title": "Steps"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"total_steps",
"completed_steps",
"progress",
"config",
"suppress_subtask_events",
"origin_instance",
"errors",
"created_at",
"updated_at"
],
"title": "WorkflowPublic",
"description": "Public representation of a workflow."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
POST /api/v1/workflows/{workflow_id}/cleanup¶
Cleanup Workflow
Description
Clean up a workflow by soft-deleting it and optionally cleaning up task files.
This endpoint marks the workflow as deleted and optionally: - Deletes all task output files (images, etc.) - Soft-deletes associated task records
The workflow and its tasks will be excluded from list queries by default
after cleanup. Use include_deleted=true on list endpoints to see them.
Args: workflow_id: ID of the workflow to clean up cleanup_tasks: Whether to clean up associated task files (default: True)
Returns: The cleaned up workflow with cleanup details including: - tasks_processed: Number of tasks that were processed - tasks_cleaned: Number of tasks successfully cleaned - deleted_paths: List of file paths that were deleted - errors: List of any errors encountered during cleanup
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
cleanup_tasks |
query | boolean | True | No | Whether to clean up associated task files |
workflow_id |
path | string | No |
Responses
{
"workflow": {
"id": "70c37f64-da9e-4675-8431-e7dbfb048164",
"name": "string",
"description": null,
"status": "PENDING",
"total_steps": 0,
"completed_steps": 0,
"progress": 10.12,
"current_step": null,
"final_step_id": null,
"final_step_result": null,
"canvas_task_id": null,
"config": {},
"suppress_subtask_events": true,
"origin_instance": "string",
"origin_zone": null,
"origin_tenant_id": null,
"origin_reference": null,
"webhook_url": null,
"error_message": null,
"errors": [
"string"
],
"started_at": null,
"completed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"is_deleted": true,
"deleted_at": null,
"steps": [
{
"id": "43882978-bae3-4b90-b9a4-3864d57784ca",
"step_id": "string",
"task_type": "string",
"config": {},
"provider_config": null,
"active_provider_capabilities": null,
"fallback_provider_type": null,
"fallback_provider_config": null,
"fallback_provider_capabilities": null,
"dependencies": [
"string"
],
"input_mappings": [
{}
],
"status": "PENDING",
"task_id": null,
"result": null,
"error_message": null,
"started_at": null,
"completed_at": null,
"retry_count": 0,
"max_retries": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
]
},
"cleanup": {
"tasks_processed": 0,
"tasks_cleaned": 0,
"deleted_paths": [
"string"
],
"errors": [
{
"task_id": "a4b4676e-afec-4eec-9903-c7c73fc0c414",
"step_id": "string",
"task_type": "string",
"error": "string"
}
]
}
}
Schema of the response body
{
"properties": {
"workflow": {
"$ref": "#/components/schemas/WorkflowPublic"
},
"cleanup": {
"$ref": "#/components/schemas/WorkflowCleanupDetail"
}
},
"type": "object",
"required": [
"workflow",
"cleanup"
],
"title": "WorkflowCleanupResponse",
"description": "Response schema for workflow cleanup endpoint."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schemas¶
CreateWorkflow¶
| Name | Type | Description |
|---|---|---|
config |
Global workflow configuration | |
description |
Optional workflow description | |
name |
string | Human-readable workflow name |
origin_instance |
string | Origin instance identifier |
origin_reference |
External reference ID for tracking | |
origin_tenant_id |
Tenant identifier for multi-tenant setups | |
origin_zone |
Origin zone identifier | |
steps |
Array<WorkflowStepDefinition> | List of steps defining the workflow DAG |
suppress_subtask_events |
boolean | Whether to suppress individual task events |
webhook_url |
URL to call when workflow completes |
FieldMapping¶
| Name | Type | Description |
|---|---|---|
from_field |
string | Output field name from source step |
from_step |
string | Step ID to get output from |
to_field |
string | Input field name in target step |
transform |
Optional transformation to apply when mapping |
HTTPValidationError¶
| Name | Type | Description |
|---|---|---|
detail |
Array<ValidationError> |
ProviderType¶
Type: string
StepStatus¶
Type: string
TaskType¶
Type: string
TransformType¶
Type: string
ValidationError¶
| Name | Type | Description |
|---|---|---|
loc |
Array<> | |
msg |
string | |
type |
string |
WorkflowCleanupDetail¶
| Name | Type | Description |
|---|---|---|
deleted_paths |
Array<string> | |
errors |
Array<WorkflowCleanupError> | |
tasks_cleaned |
integer | |
tasks_processed |
integer |
WorkflowCleanupError¶
| Name | Type | Description |
|---|---|---|
error |
string | |
step_id |
string | |
task_id |
string(uuid) | |
task_type |
string |
WorkflowCleanupResponse¶
| Name | Type | Description |
|---|---|---|
cleanup |
WorkflowCleanupDetail | |
workflow |
WorkflowPublic |
WorkflowListResponse¶
| Name | Type | Description |
|---|---|---|
limit |
integer | |
skip |
integer | |
total |
integer | |
workflows |
Array<WorkflowPublic> |
WorkflowPublic¶
| Name | Type | Description |
|---|---|---|
canvas_task_id |
||
completed_at |
||
completed_steps |
integer | |
config |
||
created_at |
string(date-time) | |
current_step |
||
deleted_at |
||
description |
||
error_message |
||
errors |
Array<string> | |
final_step_id |
||
final_step_result |
||
id |
string(uuid) | |
is_deleted |
boolean | |
name |
string | |
origin_instance |
string | |
origin_reference |
||
origin_tenant_id |
||
origin_zone |
||
progress |
number | |
started_at |
||
status |
WorkflowStatus | |
steps |
Array<WorkflowStepPublic> | |
suppress_subtask_events |
boolean | |
total_steps |
integer | |
updated_at |
string(date-time) | |
webhook_url |
WorkflowStatus¶
Type: string
WorkflowStepDefinition¶
| Name | Type | Description |
|---|---|---|
active_provider_capabilities |
List of active capabilities for this task | |
config |
Static configuration for the task (prompt, dimensions, etc.) | |
depends_on |
Array<string> | List of step IDs this step depends on |
fallback_provider_capabilities |
Capabilities for the fallback provider. | |
fallback_provider_config |
Provider-specific config for the fallback provider. | |
fallback_provider_type |
Fallback provider activated when primary exhausts all retries. | |
id |
string | Unique identifier for this step within the workflow |
input_mappings |
Array<FieldMapping> | Mappings from previous step outputs to this step's inputs |
max_retries |
integer | Maximum retry attempts for this step |
provider_config |
Provider-specific configuration (provider_type, fal_app_id, etc.) | |
task_type |
TaskType | Type of task to execute |
WorkflowStepPublic¶
| Name | Type | Description |
|---|---|---|
active_provider_capabilities |
||
completed_at |
||
config |
||
created_at |
string(date-time) | |
dependencies |
Array<string> | |
error_message |
||
fallback_provider_capabilities |
||
fallback_provider_config |
||
fallback_provider_type |
||
id |
string(uuid) | |
input_mappings |
Array<> | |
max_retries |
integer | |
provider_config |
||
result |
||
retry_count |
integer | |
started_at |
||
status |
StepStatus | |
step_id |
string | |
task_id |
||
task_type |
string | |
updated_at |
string(date-time) |
WorkflowUpdate¶
| Name | Type | Description |
|---|---|---|
description |
||
name |
||
webhook_url |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| HTTPBearer | http | bearer |