Workflows and Apps

Workflows are programmable pipelines that allow you to chain multiple AI models and tools together to automate complex creative tasks. A workflow can accept inputs, process them through multiple nodes (models/tools), and produce outputs.

Apps are workflows that can be discovered and used by anyone through the API. They provide pre-built creative pipelines that you can integrate into your applications.

Workflows

Core Concepts

Workflow: A pipeline definition containing nodes, inputs, and execution logic
Node: A step in the workflow (e.g., a model inference, transformation, or logic operation)
Inputs: Parameters that must be provided when running the workflow
Flow: The graph of nodes that defines the workflow execution order
Privacy: Controls who can access the workflow (public, private)
Status: Lifecycle state (draft, ready, deleted)

Workflow Privacy Levels

Privacy	Description
`public`	Discoverable by anyone, can be run by anyone (Apps)
`private`	Only accessible by the owning project

Workflow Status

Status	Description
`draft`	Work in progress, cannot be executed
`ready`	Complete and executable
`deleted`	Soft-deleted (not returned by API)

Endpoints

List Workflows

Retrieve a list of workflows. By default, returns private workflows for authenticated users.

Endpoint:

GET /v1/workflows

Query Parameters:

Parameter	Type	Required	Default	Description
`projectId`	string	Yes*	-	Your project ID (*optional for public workflows)
`privacy`	string	No	`private`	Filter by privacy: `public`, `private`
`status`	string	No	-	Filter by status: `draft`, `ready`
`tags`	string	No	-	Comma-separated list of tags to filter by
`pageSize`	integer	No	50	Number of results per page (1-100)
`paginationToken`	string	No	-	Token for fetching the next page

Example Request:

# List your private workflows
curl -X GET "https://api.scenario.com/v1/workflows?projectId=proj_abc123&privacy=private" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

# List public workflows (Apps)
curl -X GET "https://api.scenario.com/v1/workflows?privacy=public" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

# Filter by tags
curl -X GET "https://api.scenario.com/v1/workflows?projectId=proj_abc123&tags=upscale,image-enhancement" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

Response:

{
  "workflows": [
    {
      "id": "workflow_abc123",
      "name": "Image Upscaler",
      "description": "Upscale images to 4K resolution with AI enhancement",
      "shortDescription": "AI-powered 4K image upscaling",
      "status": "ready",
      "privacy": "public",
      "ownerId": "proj_xyz789",
      "authorId": "user_123",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-02-01T14:22:00Z",
      "tagSet": ["upscale", "image-enhancement", "tool"],
      "inputs": [
        {
          "name": "image",
          "type": "file",
          "kind": "image",
          "description": "The image to upscale",
          "required": { "always": true }
        }
      ],
      "thumbnail": {
        "assetId": "asset_thumb123",
        "url": "https://cdn.scenario.com/..."
      },
      "before": {
        "assetId": "asset_before123",
        "url": "https://cdn.scenario.com/..."
      },
      "after": {
        "assetId": "asset_after123",
        "url": "https://cdn.scenario.com/..."
      },
      "outputAssetKinds": ["image"],
      "isLocked": false,
      "flow": [...],
      "editorInfo": {...}
    }
  ],
  "nextPaginationToken": "eyJsYXN0S2V5IjoiLi4uIn0="
}

Get Workflow

Retrieve details of a specific workflow.

Endpoint:

GET /v1/workflows/{workflowId}

Path Parameters:

Parameter	Type	Required	Description
`workflowId`	string	Yes	The workflow ID

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	No*	Your project ID (*required for private workflows)

Example Request:

curl -X GET "https://api.scenario.com/v1/workflows/workflow_abc123?projectId=proj_abc123" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

Response:

{
  "workflow": {
    "id": "workflow_abc123",
    "name": "Background Remover",
    "description": "Remove backgrounds from images automatically",
    "shortDescription": "AI background removal",
    "status": "ready",
    "privacy": "public",
    "ownerId": "proj_xyz789",
    "authorId": "user_123",
    "createdAt": "2026-01-10T08:15:00Z",
    "updatedAt": "2026-01-28T11:45:00Z",
    "tagSet": ["remove-background", "editing", "tool"],
    "inputs": [
      {
        "name": "image",
        "type": "file",
        "kind": "image",
        "description": "Image to remove background from",
        "required": { "always": true }
      }
    ],
    "flow": [
      {
        "id": "node_1",
        "type": "remove-background",
        "inputs": [
          {
            "name": "image",
            "type": "file",
            "kind": "image",
            "ref": {
              "node": "workflow",
              "name": "image"
            }
          }
        ],
        "status": "pending"
      }
    ],
    "thumbnail": {
      "assetId": "asset_thumb456",
      "url": "https://cdn.scenario.com/..."
    },
    "outputAssetKinds": ["image"],
    "isLocked": false,
    "editorInfo": {...}
  }
}

Create Workflow

Create a new workflow. New workflows start with draft status.

Endpoint:

POST /v1/workflows

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Yes	Your project ID

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Workflow name
`description`	string	Yes	Full description

Example Request:

curl -X POST "https://api.scenario.com/v1/workflows?projectId=proj_abc123" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Pipeline",
    "description": "A custom workflow for image processing"
  }'

Response:

{
  "workflow": {
    "id": "workflow_new123",
    "name": "My Custom Pipeline",
    "description": "A custom workflow for image processing",
    "status": "draft",
    "privacy": "private",
    "ownerId": "proj_abc123",
    "authorId": "user_123",
    "createdAt": "2026-02-11T10:30:00Z",
    "updatedAt": "2026-02-11T10:30:00Z",
    "tagSet": [],
    "inputs": [],
    "flow": [],
    "isLocked": false,
    "editorInfo": {}
  }
}

Update Workflow

Update an existing workflow's configuration, inputs, flow, or metadata.

Endpoint:

PUT /v1/workflows/{workflowId}

Path Parameters:

Parameter	Type	Required	Description
`workflowId`	string	Yes	The workflow ID

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Yes	Your project ID

Request Body: (all fields optional)

Field	Type	Description
`name`	string	Workflow name
`description`	string	Full description
`shortDescription`	string	Short description for UI display
`status`	string	Set to `draft` or `ready`
`inputs`	array	Array of input definitions (see Input Schema below)
`flow`	array	Array of workflow nodes (see Node Schema below)
`tagSet`	array	Array of tag strings
`outputAssetKinds`	array	Expected output types: `["image"]`, `["video"]`, etc.
`before`	string	Asset ID for "before" preview (or `null` to remove)
`after`	string	Asset ID for "after" preview (or `null` to remove)
`thumbnail`	string	Asset ID for thumbnail (or `null` to remove)
`isLocked`	boolean	Lock/unlock the workflow
`editorInfo`	object	Editor-specific metadata

Example Request:

curl -X PUT "https://api.scenario.com/v1/workflows/workflow_abc123?projectId=proj_abc123" \
  -H "Authorization: Basic <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Image Pipeline",
    "shortDescription": "Quick image enhancement",
    "status": "ready",
    "inputs": [
      {
        "name": "image",
        "type": "file",
        "kind": "image",
        "description": "Input image",
        "required": { "always": true }
      },
      {
        "name": "strength",
        "type": "number",
        "description": "Enhancement strength",
        "default": 0.8,
        "min": 0,
        "max": 1,
        "required": { "always": false }
      }
    ],
    "flow": [
      {
        "id": "node_upscale",
        "type": "custom-model",
        "modelId": "model_upscaler",
        "inputs": [
          {
            "name": "image",
            "type": "file",
            "kind": "image",
            "ref": { "node": "workflow", "name": "image" }
          }
        ]
      }
    ],
    "tagSet": ["upscale", "enhancement"]
  }'

Response:

{
  "workflow": {
    "id": "workflow_abc123",
    "name": "Enhanced Image Pipeline",
    ...
  }
}

Delete Workflow

Delete a workflow. Locked workflows can only be deleted by their author.

Endpoint:

DELETE /v1/workflows/{workflowId}

Path Parameters:

Parameter	Type	Required	Description
`workflowId`	string	Yes	The workflow ID

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Yes	Your project ID

Example Request:

curl -X DELETE "https://api.scenario.com/v1/workflows/workflow_abc123?projectId=proj_abc123" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

Response:

{
  "success": true
}

Run Workflow

Execute a workflow with provided inputs. Returns a job that tracks the execution.

Endpoint:

PUT /v1/workflows/{workflowId}/run

Path Parameters:

Parameter	Type	Required	Description
`workflowId`	string	Yes	The workflow ID

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Yes	Your project ID
`dryRun`	string	No	Set to `"true"` to estimate cost without executing

Request Body:

Field	Type	Required	Description
`inputs`	object	No*	Key-value pairs matching workflow inputs (*required if workflow has required inputs)

Example Request:

curl -X PUT "https://api.scenario.com/v1/workflows/workflow_abc123/run?projectId=proj_abc123" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "image": "asset_input123",
      "strength": 0.85
    }
  }'

Response:

{
  "job": {
    "jobId": "job_wf_abc123xyz",
    "jobType": "workflow",
    "status": "in-progress",
    "progress": 15,
    "ownerId": "proj_abc123",
    "authorId": "user_123",
    "createdAt": "2026-02-11T10:35:00Z",
    "updatedAt": "2026-02-11T10:35:05Z",
    "metadata": {
      "input": {
        "image": "asset_input123",
        "strength": 0.85
      },
      "flow": [
        {
          "id": "node_upscale",
          "type": "custom-model",
          "modelId": "model_upscaler",
          "status": "processing",
          "jobId": "job_node_123",
          "inputs": [...]
        }
      ],
      "isApiKey": true
    }
  },
  "workflow": {
    "id": "workflow_abc123",
    "name": "Enhanced Image Pipeline",
    ...
  }
}

Dry Run Example:

# Estimate cost without executing
curl -X PUT "https://api.scenario.com/v1/workflows/workflow_abc123/run?projectId=proj_abc123&dryRun=true" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "image": "asset_input123"
    }
  }'

Dry Run Response:

{
  "statusCode": 402,
  "message": "Dry run completed",
  "estimatedCost": 12
}

Get Workflow Tags

Retrieve unique tags used in workflows for a project.

Endpoint:

GET /v1/workflows/tags

Query Parameters:

Parameter	Type	Required	Default	Description
`projectId`	string	Yes	-	Your project ID
`status`	string	No	`ready`	Filter by workflow status

Example Request:

curl -X GET "https://api.scenario.com/v1/workflows/tags?projectId=proj_abc123" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

Response:

{
  "tags": [
    "upscale",
    "remove-background",
    "image-enhancement",
    "video",
    "tool",
    "editing"
  ]
}

Apps (Public Workflows)

Apps are public workflows that anyone can discover and use. They're pre-built creative pipelines optimized for specific tasks.

Discover Apps

List all available apps by filtering for public workflows.

Example Request:

curl -X GET "https://api.scenario.com/v1/workflows?privacy=public&status=ready" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

Use Case Examples:

# Find background removal apps
curl -X GET "https://api.scenario.com/v1/workflows?privacy=public&tags=remove-background"

# Find upscaling apps
curl -X GET "https://api.scenario.com/v1/workflows?privacy=public&tags=upscale"

# Find all tool-type apps
curl -X GET "https://api.scenario.com/v1/workflows?privacy=public&tags=tool"

Run an App

Running an app is identical to running a workflow:

Example Request:

# Run the Background Remover app
curl -X PUT "https://api.scenario.com/v1/workflows/workflow_bg_remover/run?projectId=proj_abc123" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "image": "asset_photo123"
    }
  }'

Monitoring Job Execution

After running a workflow, monitor its progress using the Jobs API:

Get Job Status:

curl -X GET "https://api.scenario.com/v1/jobs/job_wf_abc123xyz?projectId=proj_abc123" \
  -H "Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>"

Job Status Values:

Status	Description
`queued`	Job is queued for execution
`in-progress`	Job is currently executing
`succeeded`	Job completed successfully
`failed`	Job failed with an error
`canceled`	Job was canceled

Completed Job Response:

{
  "job": {
    "jobId": "job_wf_abc123xyz",
    "jobType": "workflow",
    "status": "succeeded",
    "progress": 100,
    "createdAt": "2026-02-11T10:35:00Z",
    "updatedAt": "2026-02-11T10:35:45Z",
    "metadata": {
      "flow": [
        {
          "id": "node_upscale",
          "status": "success",
          "assets": [
            {
              "assetId": "asset_output123",
              "url": "https://cdn.scenario.com/output/..."
            }
          ]
        }
      ]
    }
  }
}

Input Schema Reference

Workflow inputs define the parameters that must be provided when running the workflow.

Common Input Types:

File Input (Image)

{
  "name": "image",
  "type": "file",
  "kind": "image",
  "description": "Input image",
  "required": { "always": true }
}

String Input

{
  "name": "prompt",
  "type": "string",
  "description": "Text prompt for generation",
  "default": "A beautiful landscape",
  "required": { "always": true }
}

Number Input

{
  "name": "strength",
  "type": "number",
  "description": "Processing strength",
  "default": 0.75,
  "min": 0,
  "max": 1,
  "step": 0.05,
  "required": { "always": false }
}

Boolean Input

{
  "name": "enable_feature",
  "type": "boolean",
  "description": "Enable advanced feature",
  "default": false,
  "required": { "always": false }
}

Select Input

{
  "name": "style",
  "type": "select",
  "description": "Output style",
  "options": ["realistic", "artistic", "cartoon"],
  "default": "realistic",
  "required": { "always": true }
}

Node Schema Reference

Nodes define the processing steps in a workflow's flow.

Node Types

Type	Description
`custom-model`	Run a custom AI model
`remove-background`	Remove image background
`logic`	Conditional logic (if/else)
`transform`	Transform data
`user-approval`	Require user approval
`workflow`	Run a sub-workflow
`generate-prompt`	Generate/refine prompts

Custom Model Node

{
  "id": "node_generation",
  "type": "custom-model",
  "modelId": "model_xyz123",
  "inputs": [
    {
      "name": "prompt",
      "type": "string",
      "ref": {
        "node": "workflow",
        "name": "prompt"
      }
    },
    {
      "name": "image",
      "type": "file",
      "kind": "image",
      "ref": {
        "node": "workflow",
        "name": "image"
      }
    }
  ]
}

Logic Node (If/Else)

{
  "id": "node_condition",
  "type": "logic",
  "logicType": "if-else",
  "inputs": [
    {
      "name": "condition",
      "type": "string",
      "ref": {
        "node": "workflow",
        "name": "mode"
      }
    }
  ],
  "logic": {
    "cases": [
      {
        "condition": "fast",
        "value": "output_fast"
      },
      {
        "condition": "quality",
        "value": "output_quality"
      }
    ],
    "default": "output_balanced"
  }
}

Transform Node

{
  "id": "node_resize",
  "type": "transform",
  "inputs": [
    {
      "name": "width",
      "type": "number",
      "value": 1024
    }
  ],
  "logic": {
    "transform": "resize(width, height)"
  }
}

Node References

Nodes can reference outputs from other nodes or workflow inputs:

{
  "ref": {
    "node": "workflow",        // or node ID like "node_1"
    "name": "prompt"           // input/output name
  }
}

Reference previous node output:

{
  "ref": {
    "node": "node_upscale",
    "name": "all"              // get all outputs
  }
}

Conditional references:

{
  "ref": {
    "conditional": ["node_check_1", "node_check_2"],
    "equal": "success"
  }
}

Workflow Locking

Locked workflows cannot be modified or deleted except by specific users.

Lock a Workflow:

curl -X PUT "https://api.scenario.com/v1/workflows/workflow_abc123?projectId=proj_abc123" \
  -H "Authorization: Basic <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "isLocked": true }'

Lock Rules:

Only the workflow author or project editors can lock/unlock
Only the author can modify or delete a locked workflow
Locking prevents accidental changes to production workflows

Error Handling

Common Error Codes

Status Code	Description
`400`	Bad Request - Invalid parameters or body
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Workflow doesn't exist
`402`	Payment Required - Returned for dry run billing estimates

Error Response Format:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid privacy. Must be one of: public, private, unlisted"
}

Best Practices

1. Use Draft Status During Development

Create workflows with draft status while building them. Set to ready only when complete and tested.

2. Leverage Tags for Organization

Use consistent tags to categorize workflows:

tool - Utility workflows (upscale, remove-background)
editing - Image/video editing workflows
generation - Content generation workflows
Custom domain tags (e.g., gaming, marketing)

3. Provide Clear Input Descriptions

Help users understand what each input does with clear descriptions and appropriate defaults.

4. Use Dry Run for Cost Estimation

Before executing expensive workflows, use dryRun=true to estimate costs.

5. Monitor Jobs Asynchronously

Workflows can take time to complete. Poll the Jobs API or use webhooks to monitor progress.

6. Lock Production Workflows

Lock workflows that are used in production to prevent accidental modifications.

7. Use Before/After/Thumbnail Assets

Add visual examples to help users understand what the workflow does.

Rate Limits

API Requests: 100 requests per minute per project
Concurrent Workflow Jobs: 10 concurrent executions per project
Workflow Size: Maximum 50 nodes per workflow

Support & Resources

API Reference: https://docs.scenario.com
Help Center: https://help.scenario.com
Discord Community: https://discord.gg/scenario
Email Support: [email protected]