@spec create(Plug.Conn.t(), map()) :: Plug.Conn.t()

Creates a new workflow in a project.

Creates a workflow with jobs, triggers, and edges. Validates the workflow structure and ensures it forms a valid DAG with no cycles.

Parameters

• conn - The Plug connection struct with the current resource assigned
• params - Map containing:
  • project_id - Project UUID (required)
  • name - Workflow name (required)
  • jobs - List of job definitions with UUIDs (required)
  • triggers - List of trigger definitions with UUIDs (required)
  • edges - List of edge definitions connecting jobs/triggers (required)

Returns

• 201 Created with workflow JSON on success
• 422 Unprocessable Entity with validation errors
• 403 Forbidden if user lacks write access

Examples

POST /api/workflows
{
  "project_id": "a1b2c3d4-...",
  "name": "Data Processing Pipeline",
  "jobs": [
    {
      "id": "job-uuid-1",
      "name": "Extract Data",
      "body": "fn(state => state)"
    }
  ],
  "triggers": [
    {
      "id": "trigger-uuid-1",
      "type": "webhook",
      "enabled": true
    }
  ],
  "edges": [
    {
      "source_trigger_id": "trigger-uuid-1",
      "target_job_id": "job-uuid-1",
      "condition": "always"
    }
  ]
}

@spec index(Plug.Conn.t(), map()) :: Plug.Conn.t()

Lists workflows with optional project filtering.

This function has two variants:

• With project_id: Returns workflows for a specific project
• Without project_id: Returns workflows across all accessible projects

Returns all workflows including their jobs, triggers, and edges.

Parameters

• conn - The Plug connection struct with the current resource assigned
• params - Map containing:
  • project_id - Project UUID (optional, filters to specific project)

Returns

• 200 OK with workflows list and empty errors map
• 404 Not Found if project doesn't exist (when project_id provided)
• 403 Forbidden if user lacks project access (when project_id provided)

Examples

# All workflows accessible to user
GET /api/workflows

# Workflows for specific project
GET /api/workflows?project_id=a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d

@spec show(Plug.Conn.t(), map()) :: Plug.Conn.t()

Retrieves a workflow by ID.

This function has two variants:

• With project_id: Validates workflow belongs to specified project
• Without project_id: Determines project access from workflow association

Returns a workflow with all its jobs, triggers, and edges.

Parameters

• conn - The Plug connection struct with the current resource assigned
• params - Map containing:
  • id - Workflow UUID (required)
  • project_id - Project UUID (optional, for validation)

Returns

• 200 OK with workflow JSON on success
• 404 Not Found if workflow doesn't exist
• 400 Bad Request if workflow exists but project_id mismatch
• 403 Forbidden if user lacks project access

Examples

# Get workflow by ID only
GET /api/workflows/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d

# Get workflow with project validation
GET /api/workflows/workflow-uuid-1?project_id=a1b2c3d4-...

@spec update(Plug.Conn.t(), map()) :: Plug.Conn.t()

Updates an existing workflow.

Modifies a workflow's structure, including its jobs, triggers, and edges. Validates the updated workflow forms a valid DAG. Prevents updates while workflow is being edited in the UI (active presence).

Parameters

• conn - The Plug connection struct with the current resource assigned
• params - Map containing:
  • project_id - Project UUID (required, must match workflow's project)
  • id - Workflow UUID (required)
  • name - Updated workflow name (optional)
  • jobs - Updated jobs list (optional)
  • triggers - Updated triggers list (optional, cannot replace existing)
  • edges - Updated edges list (optional)

Returns

• 200 OK with updated workflow JSON on success
• 422 Unprocessable Entity with validation errors
• 409 Conflict if workflow has active presence
• 403 Forbidden if user lacks write access
• 404 Not Found if workflow doesn't exist

Examples

PATCH /api/workflows/workflow-uuid-1?project_id=a1b2c3d4-...
{
  "name": "Updated Pipeline Name",
  "jobs": [...]
}