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

# Workflows

> List workflows and folders, and build a workflow from a plan - look up what a plan may use, dry-run it, then create or update the workflow.

`client.workflows` lists your workflows (`list`, `list_page`) and is the workflow **builder**; `client.folders` lists the folders that organize them. See [List workflows](#list-workflows) and [List folders](#list-folders). The builder: you describe a workflow as a **plan** (`name`, `trigger`, `steps`), look up what the plan may name, dry-run it with `compile`, and write it with `create` or `update`. It wraps the `/v1/workflows*` endpoints - the plan's full shape is in the [API reference](https://docs.engini.ai/developers/api-reference.md).

> [!WARNING]
>
> * **Writes need a workspace-scoped API key.** `create` and `update` answer `400 SCOPE_REQUIRED` for a key that has no workspace (a key created before keys were tied to a workspace). See [API keys](https://docs.engini.ai/developers/get-started/api-keys.md).
> * **A workflow is always created turned off.** Turning it on is a separate step in Engini; the API cannot do it.
> * **`update` refuses a turned-on workflow** (`409 WORKFLOW_ACTIVE`). Turn it off in the designer first.

## List workflows

```python Python theme={null}
# every match (drains 100 per page)
rows = client.workflows.list(name="lead alert", folder_id=7)

# one page, with total_count
page = client.workflows.list_page(enabled=True, sort="name asc", top=20)
for wf in page.items:
    print(wf.workflow_id, wf.name, wf.enabled)
print(page.total_count)
```

```typescript TypeScript theme={null}
// every match (drains 100 per page)
const rows = await client.workflows.list({ name: "lead alert", folderId: 7 });

// one page, with totalCount
const page = await client.workflows.listPage({ enabled: true, sort: "name asc", top: 20 });
for (const wf of page.items ?? []) console.log(wf.workflowId, wf.name, wf.enabled);
console.log(page.totalCount);
```

Each row is a workflow's summary (id, name, type, folder, enabled, blocked, timestamps, `stepsCount`) with **no steps**. Read one back as a plan with `get_plan` / `getPlan`.

| Filter | Meaning |
| - | - |
| `name`, `folder_name` / `folderName` | Case-insensitive **substring** matches, so several rows can match: compare `name` yourself for an exact one |
| `folder_id` / `folderId` | One folder, by the id of `client.folders` (an integer here, a string on a folder). `0` means workflows in no folder |
| `enabled`, `blocked`, `deleted` | Booleans. Deleted workflows are excluded unless `deleted` is true |
| `deleted_after`, `updated_after`, `updated_before`, `last_run_after`, `last_run_before` | Timestamp bounds (`deleted_after` / `deletedAfter` implies `deleted=true`) |
| `type` | A trigger type, for example `instant`, `automated` or `scheduled` |
| `connection_id` / `connectionId`, `created_by` / `createdBy`, `updated_by` / `updatedBy` | Narrow by connection or account user |
| `sort` | `workflowId`, `name`, `updatedAt` or `lastRunAt`, e.g. `"name asc,updatedAt desc"`. Default `workflowId desc` |

* **`list`** with no `top` drains every match, 100 per page. Pass `top` for one bounded page (server cap 100), and `offset` with it to read a later one. `offset` without `top` raises `EnginiClientError`.
* **`list_page` / `listPage`** returns one page with `total_count` / `totalCount`.
* A workflow deleted while `list` is draining can still be skipped.
* Table automations are not listed. A workspace-scoped API key sees only its own workspace and environment; see [API keys](https://docs.engini.ai/developers/get-started/api-keys.md).

## List folders

```python Python theme={null}
folders = client.folders.list(name="sales")
sales = next(f for f in folders if f.name == "Sales")
rows = client.workflows.list(folder_id=int(sales.id))
```

```typescript TypeScript theme={null}
const folders = await client.folders.list({ name: "sales" });
const sales = folders.find((f) => f.name === "Sales");
const rows = await client.workflows.list({ folderId: Number(sales?.id) });
```

`client.folders` lists **workflow** folders (it always sends `type=workflow`; table folders are not served). Each folder has `id` (a string), `name`, `workspaceId`, `environmentId` and `itemsCount`. Folder names are unique only within one workspace and environment, so two folders can share a name: check `workspaceId` and `environmentId`.

| Method | Returns |
| - | - |
| `list` | Every match, or one page when you pass `top` (`offset` needs `top`). `name` is a case-insensitive substring match; `sort` is `name` or `createdAt`, default `name asc` |
| `list_page` / `listPage` | One page with `total_count` / `totalCount` |

## Look up what a plan may use

```python Python theme={null}
hits = client.workflows.search_catalog(q="post message", app="slack", kind="action")
schema = client.workflows.get_schema("slack.post_message", connection_id=42)
channels = client.workflows.get_options(
    "slack.post_message", field="channel", connection_id=42
)
connections = client.workflows.list_connections(app="slack")
tables = client.workflows.list_tables()
columns = client.workflows.list_table_columns(tables[0].id)
```

```typescript TypeScript theme={null}
const hits = await client.workflows.searchCatalog({ q: "post message", app: "slack", kind: "action" });
const schema = await client.workflows.getSchema("slack.post_message", { connectionId: 42 });
const channels = await client.workflows.getOptions("slack.post_message", {
  field: "channel",
  connectionId: 42,
});
const connections = await client.workflows.listConnections({ app: "slack" });
const tables = await client.workflows.listTables();
const columns = await client.workflows.listTableColumns(tables[0].id);
```

| Method | Returns |
| - | - |
| `search_catalog` / `searchCatalog` | Hits `{slug, kind, app, name, description, score}`. `kind` is `action`, `trigger` or `block`; `app` narrows to one application; `table` narrows to a table's trigger and actions; `top` caps the hits. The `slug` is what `get_schema` and the plan take |
| `get_schema` / `getSchema` | The input/output schema of one catalog entry. Pass `connection_id` / `connectionId` to read the fields that depend on the connected system live; without it you get the static schema |
| `get_options` / `getOptions` | The `{id, label}` values a dropdown field accepts, read through one of your connections. `depends_on` / `dependsOn` is a `{field: value}` map of the parent fields this one depends on |
| `list_connections` / `listConnections` | Your connections usable in a plan step, optionally narrowed to one app slug |
| `list_tables` / `listTables` | Your tables `{id, name}` in the key's workspace and environment |
| `list_table_columns` / `listTableColumns` | A table's columns as a table automation reads them. `trigger` is the automation's Tables trigger slug |

These are reads. Reading a schema with a connection (`connection_id` / `connectionId`) is rate limited per key.

## Dry-run, then write

```python Python theme={null}
plan = {"name": "Notify sales", "trigger": trigger, "steps": steps}   # a dict or a WorkflowPlan

result = client.workflows.compile(plan)         # nothing is written
if result.has_errors:
    for d in result.diagnostics:
        print(d.severity, d.code, d.step_key, d.message)
else:
    created = client.workflows.create(plan, folder_id=7)
    print(created.workflow_id, created.designer_url, created.revision_id)   # turned off
```

```typescript TypeScript theme={null}
const plan = { name: "Notify sales", trigger, steps };

const result = await client.workflows.compile({ plan });   // nothing is written
if (result.hasErrors) {
  for (const d of result.diagnostics ?? []) console.log(d.severity, d.code, d.stepKey, d.message);
} else {
  const created = await client.workflows.create({ plan, folderId: 7 });
  console.log(created.workflowId, created.designerUrl, created.revisionId);   // turned off
}
```

* **`compile`** answers `200` even when the plan has errors: the result carries `has_errors` / `hasErrors` and every diagnostic. Pass `base_workflow_id` / `baseWorkflowId` to compile the plan as an edit of a saved workflow.
* **`create`** raises `EnginiBuilderError` with code `PLAN_HAS_ERRORS` (HTTP 422, the diagnostics on the error) for a plan with errors, and writes nothing. It returns `workflow_id`, `designer_url`, `revision_id`, `diagnostics`, `workspace_id`, `environment_id` and, for a manual-webhook trigger, `webhook_url`.
* A Python plan may be a `WorkflowPlan` or the equivalent dict. A malformed dict raises `EnginiClientError` before any request is sent.

## Edit a saved workflow

```python Python theme={null}
plan = client.workflows.get_plan(1234)           # the saved workflow, read back as a plan
# ... edit the plan ...
updated = client.workflows.update(1234, plan, expected_revision_id=3)
```

```typescript TypeScript theme={null}
const plan = await client.workflows.getPlan(1234);
// ... edit the plan ...
const updated = await client.workflows.update(1234, { plan, expectedRevisionId: 3 });
```

`get_plan` returns the plan plus a `revisionId` (an opaque token that moves on every write) and, for a manual-webhook trigger, `webhookUrl`. The plan reader ignores both extra members, so the body can be sent back as the plan unchanged. Pass the `revisionId` you read as `expected_revision_id` / `expectedRevisionId` so a stale save is refused instead of overwriting someone else's edit.

## Handle refusals

Every builder refusal is an `EnginiBuilderError` (a subclass of `EnginiAPIError`). It is mapped from the response **body** - its `code` - not from the status, so a builder `409` is **not** an `EnginiConflictError`: branch on `code`.

| Member | Meaning |
| - | - |
| `code` | `PLAN_HAS_ERRORS`, `REVISION_CONFLICT`, `WORKFLOW_ACTIVE`, `SCOPE_REQUIRED`, ... (`error_code` mirrors it) |
| `status` | The HTTP status |
| `path` | The request member the refusal is about, when there is one |
| `fix` | What to do about it, when the builder knows |
| `diagnostics` | With `PLAN_HAS_ERRORS`: every diagnostic - `severity`, `code`, `message`, `step_key` / `stepKey`, `field` |
| `current_revision_id` / `currentRevisionId` | With `REVISION_CONFLICT`: the workflow's revision now |

```python Python theme={null}
from engini.errors import EnginiBuilderError

try:
    client.workflows.update(1234, plan, expected_revision_id=3)
except EnginiBuilderError as e:
    if e.code == "REVISION_CONFLICT":
        print("saved since revision 3; now", e.current_revision_id)
    elif e.code == "WORKFLOW_ACTIVE":
        print(e.fix)
    else:
        raise
```

```typescript TypeScript theme={null}
import { EnginiBuilderError } from "@engini/sdk";

try {
  await client.workflows.update(1234, { plan, expectedRevisionId: 3 });
} catch (e) {
  if (!(e instanceof EnginiBuilderError)) throw e;
  if (e.code === "REVISION_CONFLICT") console.log("saved since revision 3; now", e.currentRevisionId);
  else if (e.code === "WORKFLOW_ACTIVE") console.log(e.fix);
  else throw e;
}
```

The error tree and the other classes are on [Errors & pagination](https://docs.engini.ai/developers/sdk/errors-pagination.md).


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