> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capsule.new/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow API

> `app.workflow(...)`, `WorkflowInput`, and workflow handler decorators.

Workflows are named session-backed surfaces registered on `App`.

## `app.workflow(...)`

```python theme={null}
wf = app.workflow(
    "Research Company",
    scope="user",
    icon="search",
    description="Collect context and draft a brief.",
)
```

Arguments:

| Argument | Meaning |
| - | - |
| `name` | Sidebar label and workflow name |
| `scope` | `"user"`, `"owner"`, or `"app"` |
| `icon` | Sidebar icon name |
| `description` | Short description shown in the workflow launcher |

The returned `Workflow` object registers handlers.

## `@workflow.ui()`

Registers an optional launcher UI. The function must return `cpsl.ui.WorkflowShell`.

```python theme={null}
@wf.ui()
def ui():
    return cpsl.ui.WorkflowShell(
        "Research Company",
        children=[
            cpsl.ui.FormSection(
                "Input",
                children=[
                    cpsl.ui.TextInput("Company", name="company", required=True)
                ],
            ),
            cpsl.ui.ActionBar(
                children=[cpsl.ui.SubmitButton("Start", primary=True)]
            ),
        ],
    )
```

If no launcher UI is registered, the workflow opens a plain chat composer.

## `@workflow.start()`

Registers the handler called when a workflow run starts.

```python theme={null}
@wf.start()
async def start(session: cpsl.Session, input: cpsl.WorkflowInput):
    await session.reply(f"Starting: {input.get('company')}")
```

## `@workflow.action(name)`

Registers a named structured action.

```python theme={null}
@wf.action("approve")
async def approve(session: cpsl.Session, input: cpsl.WorkflowInput):
    await session.reply(f"Approved {input['id']}")
```

## `@workflow.message()`

Registers the freeform chat handler for an active workflow session.

```python theme={null}
@wf.message()
async def message(session: cpsl.Session, msg: cpsl.Message):
    await session.reply(f"Continuing with: {msg.text}")
```

## `WorkflowInput`

`WorkflowInput` wraps submitted launcher or action data.

```python theme={null}
value = input["company"]
same_value = input.company
optional = input.get("notes", "")
payload = input.to_dict()
```

It behaves like a dict and also supports attribute access.

## Launcher widgets

Workflow launcher UIs use the same `cpsl.ui` namespace.

Common workflow widgets:

| Widget | Purpose |
| - | - |
| `WorkflowShell(title, children=...)` | Root workflow launcher |
| `FormSection(label, children=...)` | Labelled form section |
| `TextInput(...)` | Text input |
| `NumberInput(...)` | Number input |
| `Select(...)` | Select input |
| `FileInput(...)` | File upload input |
| `ActionBar(...)` | Submit/action controls |
| `SubmitButton(...)` | Submit to `@workflow.start()` or a named action |
| `RunStatus(...)` | Current run state |
| `RunList(...)` | List of workflow runs |

## See also

* [Workflows](https://docs.capsule.new/features/workflows.md)
* [Chat And Sessions](https://docs.capsule.new/features/chat-and-sessions.md)
* [UI And Pages Reference](https://docs.capsule.new/reference/ui-and-pages.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.