API Reference

Create Automation

Two examples: AI generation on card created, and update a field when a card moves to a phase

Before You Begin

Prerequisites

  • You must have access to the repos involved:
    • For most automations: admin permission on both the event repo and the action repo.
    • For scheduler automations: permission requirements differ; generally you must be able to manage the action repo.

Create an Automation

AI action example (generate_with_ai using field internal_id)

Inputs

  • name: Display name of the automation.
  • action_id: Must be generate_with_ai for AI generation.
  • event_id: Set to card_created to trigger on new cards.
  • event_repo_id and action_repo_id: Pipe IDs where the trigger runs and where the action writes. See "Get Resource IDs" → Pipe ID and UUID.
  • action_params.aiParams.value: Prompt text. Reference source fields from the card with %{INTERNAL_ID} (e.g., %{132}).
  • action_params.aiParams.fieldIds: Destination field internal IDs for the AI output (e.g., 133). See "Get Resource IDs" → Field internal_id for Start Form and Phase Fields.
  • condition: Optional filter tree to control when the automation runs. Contains:
    • expressions: Array of condition expressions. Each expression has:
      • structure_id: Unique identifier for this expression within the condition (use incremental numbers: 0, 1, 2, etc.).
      • field_address: The field's internal ID to evaluate (leave empty "" for placeholder conditions).
      • operation: Comparison operation. Valid options: 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.
      • value: The value to compare against (leave empty "" for placeholder conditions).
    • expressions_structure: Defines how expressions are combined using logical operators. Use nested arrays where each sub-array represents a group of expressions connected by AND logic, and different sub-arrays are connected by OR logic.
mutation {
  createAutomation(
    input: {
  name: "Translate fields with AI",
  action_id: "generate_with_ai",
  event_id: "card_created",
  event_repo_id: "22",
  action_repo_id: "22",
  action_params: {
    aiParams: {
      value: "Translate accurately, maintaining the original meaning, context, and tone of the following inputs: %{132}\nOutput language: English",
      fieldIds: [
        133
      ]
    }
  },
  condition: {
    expressions: [
      {
        structure_id: 0,
        field_address: "",
        operation: "",
        value: ""
      }
    ],
    expressions_structure: [
      [
        0
      ]
    ]
  }
}
  ) {
    automation {
      id
      name
      action_id
      event_id
      action_repo_v2 { ... on Pipe { id } ... on Table { id } }
      event_repo { id }
      active
    }
    error_details {
      object_name
      object_key
      messages
    }
  }
}

Response:

{
  "data": {
    "createAutomation": {
      "automation": {
        "id": "20",
        "name": "Translate fields with AI",
        "action_id": "generate_with_ai",
        "event_id": "card_created",
        "action_repo_v2": {
          "id": "22"
        },
        "event_repo": {
          "id": "22"
        },
        "active": true
      },
      "error_details": null
    }
  }
}

Response explained

  • automation.id: Created automation identifier.
  • automation.name/action_id/event_id: Echoes the input for verification.
  • action_repo_v2.id / event_repo.id: Repo/Pipe IDs used.
  • active: Whether the automation is enabled.
  • error_details: Null when creation succeeds; otherwise includes validation errors.

Notes:

  • Repo IDs are the same as Pipe IDs. Get them in “Get Resource IDs” → Pipe ID and UUID.
  • Use field internal_id values:
    • In the prompt: %{INTERNAL_ID} (e.g., %{132}).
    • For outputs: list destination internal_id(s) in aiParams.fieldIds (e.g., 133).
  • To fetch internal_id values, use “Get Resource IDs” → Field internal_id for Start Form and Phase Fields:
    • pipe(id: <PIPE_ID>) { start_form_fields { label internal_id } phases { fields { label internal_id } } }.

Update a field when a card is moved to a phase

Inputs

  • name: Display name of the automation.
  • action_id: update_card_field to update field values on a card.
  • event_id: card_moved to trigger on phase transitions.
  • event_repo_id / action_repo_id: Pipe IDs for trigger and action. See "Get Resource IDs" → Pipe ID and UUID.
  • event_params: Configuration for the triggering event. Contains:
    • to_phase_id: Destination phase ID to match the move. Automation only triggers when cards move to this specific phase. See "Get Resource IDs" → Phase ID.
  • action_params: Configuration for the field update action. Contains:
    • field_map: Array of field mappings. Each mapping has:
      • fieldId: Destination field internal ID where the value will be written.
      • inputMode: How to populate the field. Use copy_from to copy from another field (using %{FIELD_ID} syntax) or write a literal value; use fixed_value for static hardcoded values.
      • value: Source value or field placeholder. Use %{INTERNAL_ID} to reference source fields (e.g., %{134}) or provide static text.
    • fields_map_order: Array of field internal IDs defining the order in which fields are updated.
    • card_id: Target card identifier. Use "%{id}" to reference the card that triggered the event.
  • condition: Optional filter tree to control when the automation runs. Same structure as described in the AI example above.
mutation {
  createAutomation(input: 
  {
  name: "Update the field when card is moved to Doing",
  action_id: "update_card_field",
  event_id: "card_moved",
  event_repo_id: "23",
  action_repo_id: "23",
  action_params: {
    field_map: [
      {
        fieldId: "135",
        inputMode: "copy_from",
        value: "%{134}"
      }
    ],
    fields_map_order: [
      135
    ],
    card_id: "%{id}"
  },
  condition: {
    expressions: [
      {
        structure_id: 0,
        field_address: "",
        operation: "",
        value: ""
      }
    ],
    expressions_structure: [
      [
        0
      ]
    ]
  },
  event_params: {
    to_phase_id: "328"
  }
}) {
    automation {
      id
      action_params {
        authenticationAddTo
        authenticationKey
        authenticationType
        body
        card_id
        email_template_id
        hasAuthenticationValue
        headers
        httpMethod
        strategy
        to_phase_id
        url
      }
    }
  }
}

Response:

{
  "data": {
    "createAutomation": {
      "automation": {
        "id": "22",
        "action_params": {
          "authenticationAddTo": null,
          "authenticationKey": null,
          "authenticationType": null,
          "body": null,
          "card_id": "%{id}",
          "email_template_id": null,
          "hasAuthenticationValue": false,
          "headers": null,
          "httpMethod": null,
          "strategy": null,
          "to_phase_id": null,
          "url": null
        }
      }
    }
  }
}

Response explained

  • automation.id: Created automation identifier.
  • action_params.card_id: Confirms it targets the moved card via %{id} from the event.
  • Other fields shown as null are not used by this action type and remain unset.
  • If validation fails, error_details would be provided (omitted here because success).

Conditions

The optional condition field filters when an automation actually executes after the event fires. For the full reference — expressions, AND/OR logic, available operations by field type, and examples — see Conditions.

Events and Actions Parameters

For the full reference of event_params and action_params accepted by each event and action, see:

See also

Updated 4 days ago

Updated 4 days ago