Automations

Traditional automations (if/then rules), AI automations (prompt-driven), task automations, and simulation. 16 MCP tools.

For AI agents (conversational agents with behaviors), see skills/ai-agents/pipefy-ai-agents/SKILL.md.

Traditional automations (rules engine)

Tool (MCP)	CLI	Purpose
`get_automations`	`pipefy automation list`	List all automations for a pipe.
`get_automation`	`pipefy automation get`	Single automation with full rule config — returns `event_params` and `action_params` (including `aiParams` for AI rules).
`create_automation`	`pipefy automation create`	Create an if/then rule. `active` defaults to true. First-class typed `condition` (see Conditions); other fields via `extra_input` .
`update_automation`	`pipefy automation update`	Patch a rule: first-class typed `condition` (see Conditions) and/or `extra_input` .
`delete_automation`	`pipefy automation delete`	(Two-step destructive)
`simulate_automation`	`pipefy automation simulate`	AI-only dry-run ( `generate_with_ai` action).
`get_automation_events`	`pipefy automation events list`	Available trigger events.
`get_automation_event_attributes`	`pipefy automation event-attributes`	Official `field_map.value` event-attribute tokens.
`get_automation_actions`	`pipefy automation actions list`	Available action types for a pipe.
`create_send_task_automation`	`pipefy automation send-task create`	Shortcut for send-a-task rules.

Logs, usage, and job exports for automations live in skills/observability/pipefy-observability/SKILL.md (

get_automation_logs

get_automation_logs_by_repo

get_automations_usage

export_automation_jobs

, and related tools).

AI automations (prompt-driven)

Tool (MCP)	CLI	Purpose
`get_ai_automations`	`pipefy ai-automation list`	List AI automations for a pipe.
`get_ai_automation`	`pipefy ai-automation get`	Full config including prompt, fields, condition.
`create_ai_automation`	`pipefy ai-automation create`	Create a prompt-driven automation (requires AI enabled on the pipe).
`update_ai_automation`	`pipefy ai-automation update`	Change name, `active` , prompt, `field_ids` , or `condition` .
`delete_ai_automation`	`pipefy ai-automation delete`	(Two-step destructive)
`validate_ai_automation_prompt`	`pipefy ai-automation validate-prompt`	Pre-flight check. Returns `{valid, problems, warnings, field_map}` — also detects prompt `%{id}` ∩ `field_ids` overlap.

Steps — create an AI automation

Discover field
internal_id
s for any field referenced in the prompt:
```
get_phase_fields phase_id="<phase_id>"
```
Build the prompt with
```
%{<internal_id>}
```
references. Pipefy silently rejects prompts with no field reference (returns
```
"Input parameters are required."
```
).
Important: the
```
%{...}
```
wrapper and a numeric field
```
internal_id
```
from your pipe are required — the exact digits in examples below (e.g.
```
900000101
```
) are fictional placeholders. Discover real IDs via
```
get_phase_fields
```
/
```
get_start_form_fields
```
; do not copy example numbers from docs.

Validate the prompt:

validate_ai_automation_prompt pipe_id=67890 prompt="Summarize %{900000101} and comment." field_ids=["900000101"]

Returns

valid:true|false

problems

warnings

field_map

. Catches mistakes in one read-only call vs 2–3 failed mutation roundtrips.

Create the automation (only if

valid:true

create_ai_automation pipe_id=67890 trigger_event="card_created" prompt="Summarize %{900000101} and comment." field_ids=["900000101"]

Steps — create a traditional automation

Discover events for the pipe:
```
get_automation_events pipe_id=67890
```
.
Discover actions for the pipe:
```
get_automation_actions pipe_id=67890
```
. (Always discover first; never guess
```
trigger_id
```
/
```
action_id
```
.)
Build the rule with the discovered IDs and call
```
create_automation
```
.
Verify by reading back with
```
get_automation
```
.

Conditions — gate a rule on field tests

create_automation

and

update_automation

take a first-class

condition

(CLI:

--condition

). Do not guess the shape from GraphQL introspection — it is:

json

{
  "expressions": [
    {"field_address": "900000101", "operation": "equals", "value": "Done", "structure_id": 0}
  ],
  "expressions_structure": [[0]]
}

field_address

is the field internal_id
(numeric, from

get_start_form_fields

get_phase_fields

), not the slug. For a connected card's field use

<connectorFieldId>.<targetFieldId>

operation

(soft enum — any value is passed through, the API validates):

equals

not_equals

present

blank

string_contains

string_not_contains

number_greater_than

number_less_than

date_is_today

date_is_yesterday

date_in_current_week

date_in_last_week

date_in_current_month

date_in_last_month

date_in_current_year

date_in_last_year

date_is

date_is_after

date_is_before

. Omit

value

for

present

blank

```
expressions_structure
```
groups expressions (by
```
structure_id
```
) as AND-of-ORs: inner arrays are OR'd, the inner arrays are AND'd —
```
[[0, 1], [2]]
```
is
```
(expr0 OR expr1) AND expr2
```
.

Omit

condition

to leave a traditional rule unconditional (no default is injected). A

condition

argument wins over any

condition

extra_input

Steps — update a card field with a dynamic value

Use when the user wants an if/then rule to stamp or copy values onto the triggering card (for example, set a datetime when

card_created

fires). This is create_automation
with

action_id: update_card_field

and

extra_input.action_params.field_map

— not the MCP tool

update_card_field

(that tool uses field slug for one-off card edits).

Discover field
internal_id
s (digits only — never slug in

fieldId

get_start_form_fields pipe_id=67890
get_phase_fields phase_id="<phase_id>"

Discover trigger, action, and event-attribute tokens:

get_automation_events pipe_id=67890
get_automation_actions pipe_id=67890
get_automation_event_attributes

For

update_card_field

acceptedParameters

omits

field_map

; use the payload shape below (see

docs/mcp/tools/automations-and-ai.md

). Prefer

value_token

from

get_automation_event_attributes

when stamping execution time.

Create disabled (

active=false

) so the rule does not fire while you verify:

create_automation pipe_id=67890 name="Stamp execution time on new cards" trigger_id=card_created action_id=update_card_field active=false extra_input={"action_params":{"card_id":"%{id}","field_map":[{"fieldId":"<destination_internal_id>","inputMode":"copy_from","value":"%{automation_event_execution_datetime}"}],"fields_map_order":["<destination_internal_id>"]}}

Common

value

tokens when

inputMode

copy_from

%{id}

(also use in

card_id

%{created_at}

%{automation_event_execution_datetime}

%{<other_internal_id>}

to copy another field.

Verify persisted config:

get_automation automation_id=<id>

Confirm

action_params.field_map

round-tripped.

Enable when correct:

update_automation automation_id=<id> extra_input={"active":true}

Steps — simulate a traditional automation

simulate_automation

is AI-only today (only

generate_with_ai

action_id

is accepted). For non-AI rules, watch

get_automation_logs

after the trigger fires.

Read a working rule first:

get_automation automation_id=<id>

— copy

event_params

and

action_params

verbatim.

Simulate with a real sample card:

simulate_automation pipe_id=67890 action_id=generate_with_ai sample_card_id=456

Result is async: returns
```
simulation_id
```
+
```
status:"processing"
```
with null
```
simulationResult
```
. No polling tool exists in v0.1 — wait, then re-invoke
```
get_automation_logs
```
or
```
simulate_automation
```
.

Traditional automation preflight

field_map

destination

fieldId

create_automation

, when

extra_input.action_params.field_map

is present, the SDK checks each

fieldId

against numeric

internal_id

values on the action pipe (

action_repo_id

, default

pipe_id

). Slug-shaped

fieldId

values and unknown numeric ids fail before GraphQL with

success: false

and the offending id. Recovery:

get_start_form_fields

get_phase_fields

→ use

internal_id

, not slug.

Phase transition (

move_single_card

)

For

move_single_card

actions with trigger

card_moved

, create_automation
only validates that the destination phase is reachable from the source via

cards_can_be_moved_to_phases

(same read-only data as

move_card_to_phase

update_automation

does not run this check.

If invalid, the tool returns

success: false

with a text error message listing allowed destination phases by name and id, plus a hint that transition rules are configured in the Pipefy UI only (not editable via API). There is no structured

valid_destinations

field on this envelope.

Recovery: read the allowed phases in

error.message

, or call

get_phase_allowed_move_targets(phase_id=<source_phase_id>)

on the source phase from

event_params.to_phase_id

, then re-issue

create_automation

with a permitted destination phase id.

Notification disambiguation

Pick the right tool for "notification" intent:

User signal words	Tool	Why
"notificação", "tarefa", "lembrete para alguém validar"	`create_send_task_automation`	Built-in: handles `event_id` , `task_title` , `recipients` , optional `event_params` and `condition` .
"enviar e-mail", "responder ao cliente"	`send_email_with_template` / `send_inbox_email` (members-email-webhooks)	Email surface, not automations.
"webhook", "chamar serviço externo"	`create_webhook` (members-email-webhooks)	HTTP callback on card events.
"automação", "regra if/then"	`create_automation`	Generic rules engine.

Do NOT hand-build

action_params.taskParams

via

create_automation

when

create_send_task_automation

is the right tool.

Agentic + human-in-the-loop pattern

Combine AI automations with task automations so AI handles routine work and humans validate high-impact decisions. The highest-leverage pattern in the catalog.

Example flow:

```
create_ai_automation
```
: when card enters "Análise", AI fills classification and risk fields automatically.
```
create_send_task_automation
```
: when the AI-filled field is updated, send a task to the manager — "Validate the classification on card [title]".
```
create_automation
```
or
```
create_field_condition
```
: when the manager marks "Approved", move the card to the next phase.

Use this pattern for approvals, financial decisions, content publication, and any step where errors have real-world consequences. See also: skills/process-design/ Orchestration patterns.

Success criteria

```
get_automation
```
returns the new rule with correct trigger and actions.
```
validate_ai_automation_prompt
```
returns
```
valid:true
```
before AI automation creation.
```
simulate_automation
```
(AI rules) eventually returns a non-null
```
simulationResult
```
.

Failure modes

simulate_automation
is AI-only. Only
```
generate_with_ai
```
```
action_id
```
accepted. For traditional rules, use
```
get_automation_logs
```
after the rule fires.

Async simulation result.

simulate_automation

returns

simulation_id

status:"processing"

+ null

simulationResult

; no polling tool in v0.1. Wait, then call

get_automation_logs

or re-invoke

simulate_automation

validate_ai_automation_prompt
returns
valid:false
. Read
```
problems
```
(per-field) and
```
warnings
```
. Most common: prompt missing
```
%{internal_id}
```
reference, or
```
field_ids
```
overlap with prompt
```
%{id}
```
tokens.

create_automation
cycle detection. Same-pipe

card_created

create_card

rejected with

"This automation can't be created! It would result in an endless card creation cycle."

Use a different trigger, target a different pipe, or use

update_card

instead.

create_automation
fails with unknown event/action. Always run
```
get_automation_events
```
+
```
get_automation_actions
```
first; do not guess IDs.
Phase transition error on
move_single_card
. Only
```
create_automation
```
preflights transitions. Read allowed phase ids in the error text or call
```
get_phase_allowed_move_targets
```
, then re-issue with a permitted destination. UI is the only edit surface for transition rules.
Cross-pipe
PERMISSION_DENIED
. SA must be member of both source and destination pipes for
```
create_connected_card
```
/ cross-pipe
```
create_card
```
. Recovery:
```
get_pipe_members
```
+
```
invite_members
```
.
get_automation_logs_by_repo
returns empty. Pipe has no traditional automation executions; not an error. AI agent executions are separate (see
```
get_ai_agent_logs
```
).
create_send_task_automation
fires immediately when
active=true
. Pass
```
active=false
```
first if you want to wire it up before the rule starts firing. The 2026-04-16 orphaned-task incident is the cautionary tale.

update_automation
API asymmetry.

create_automation

takes a top-level

active

param;

update_automation

requires

extra_input={"active": false}

. Pass

active

through

extra_input

when toggling on an existing rule.

action_repo_id
semantics. For cross-pipe actions (
```
create_connected_card
```
,
```
create_card
```
into another pipe), this is the destination pipe, not the source.
Simulation reuses real rule params. Before simulating, call
```
get_automation
```
to read
```
event_params
```
and
```
action_params
```
of a working rule and pass them verbatim. Don't hand-craft params.
field_map
uses slug in
fieldId
. Preflight rejects non-numeric
```
fieldId
```
before GraphQL; slugs (e.g.
```
due_date
```
) used to surface as
```
INTERNAL_SERVER_ERROR
```
. Recovery:
```
get_start_form_fields
```
/
```
get_phase_fields
```
→ use
```
internal_id
```
.
Unknown
field_map

fieldId
.
```
create_automation
```
preflight fails with the offending id when the destination field is not on the action pipe. Re-discover ids on
```
action_repo_id
```
(not only the trigger pipe for cross-pipe actions).
Used
update_card_field
MCP tool for a rule. That tool updates one card by slug; automations need
```
create_automation
```
+
```
field_map
```
with numeric
```
fieldId
```
.
Missing or wrong
card_id
. Set
```
action_params.card_id
```
to
```
"%{id}"
```
for the triggering card; empty/wrong values prevent the intended update.
Token typo in
field_map.value
. Typos in
```
%{…}
```
templates leave fields unchanged at runtime. Compare with Automation Event Attributes and a working rule from
```
get_automation
```
.
Rule runs but field unchanged. Check
```
get_automation_logs
```
/
```
get_automation_logs_by_repo
```
for execution errors; invalid
```
fieldId
```
may fail silently (no card update).

pipefy-automations

NPX Install

Tags

SKILL.md Content

Automations

Traditional automations (rules engine)

AI automations (prompt-driven)

Steps — create an AI automation

Steps — create a traditional automation

Conditions — gate a rule on field tests

Steps — update a card field with a dynamic value

Steps — simulate a traditional automation

Traditional automation preflight

`field_map`
destination
`fieldId`

Phase transition (
`move_single_card`
)

Notification disambiguation

Agentic + human-in-the-loop pattern

Success criteria

Failure modes

See also

pipefy-automations

NPX Install

Tags

SKILL.md Content

Automations

Traditional automations (rules engine)

AI automations (prompt-driven)

Steps — create an AI automation

Steps — create a traditional automation

Conditions — gate a rule on field tests

Steps — update a card field with a dynamic value

Steps — simulate a traditional automation

Traditional automation preflight

field_map destination fieldId

Phase transition (move_single_card)

Notification disambiguation

Agentic + human-in-the-loop pattern

Success criteria

Failure modes

See also

`field_map`
destination
`fieldId`

Phase transition (
`move_single_card`
)