Skip to main content
client.workflows lists your workflows (list, list_page) and is the workflow builder; client.folders lists the folders that organize them. See List workflows and 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.
  • 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.
  • 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

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.
  • 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.

List folders

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.

Look up what a plan may use

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

Dry-run, then write

  • 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

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.
The error tree and the other classes are on Errors & pagination.