# Automation rules endpoints

> When-then rules on a workflow's runs (set fields, status, labels, assignees; notify; send to a webhook) and their execution history. Every operation with parameters, body, responses, errors and examples.

Source: https://developers.processcart.com/reference/automation-rules

When-then rules on a workflow's runs (set fields, status, labels, assignees; notify; send to a webhook) and their execution history.

Rules carry no `revision`, and no operation here reads `Expected-Revision` (the header, or the SDK's `expectedRevision` option, is ignored): an update applies to the rule as it is stored, and the last write wins.

Base URL `https://app.processcart.com/api/v1`. Every operation below is also in the [OpenAPI document](https://developers.processcart.com/openapi.json) and the [interactive reference](https://developers.processcart.com/reference).

| Operation | Method and path | Scope |
| --- | --- | --- |
| [List automation rules](#listAutomationRules) | <code class="pc-docs-wrap">GET /v1<wbr>/automation-rules</code> | Scope `rules:manage` |
| [Create an automation rule](#createAutomationRule) | <code class="pc-docs-wrap">POST /v1<wbr>/automation-rules</code> | Scope `rules:manage` |
| [Get an automation rule](#getAutomationRule) | <code class="pc-docs-wrap">GET /v1<wbr>/automation-rules<wbr>/{id}</code> | Scope `rules:manage` |
| [Update an automation rule](#updateAutomationRule) | <code class="pc-docs-wrap">PATCH /v1<wbr>/automation-rules<wbr>/{id}</code> | Scope `rules:manage` |
| [Delete an automation rule](#deleteAutomationRule) | <code class="pc-docs-wrap">DELETE /v1<wbr>/automation-rules<wbr>/{id}</code> | Scope `rules:manage` |
| [Turn an automation rule on](#enableAutomationRule) | <code class="pc-docs-wrap">POST /v1<wbr>/automation-rules<wbr>/{id}<wbr>/enable</code> | Scope `rules:manage` |
| [Turn an automation rule off](#disableAutomationRule) | <code class="pc-docs-wrap">POST /v1<wbr>/automation-rules<wbr>/{id}<wbr>/disable</code> | Scope `rules:manage` |
| [List a rule's executions](#listAutomationRuleExecutions) | <code class="pc-docs-wrap">GET /v1<wbr>/automation-rules<wbr>/{id}<wbr>/executions</code> | Scope `rules:manage` |

## GET /v1/automation-rules
**List automation rules.** Scope `rules:manage` · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated (`{ data, nextCursor, hasMore }`). Operation id `listAutomationRules` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/GET/v1/automation-rules).

Lists the workspace's automation rules, newest first, each with its trigger, filter, conditions, actions and enabled state. Filter by `workflowId` or `enabled`. `updatedSince` turns the list into an incremental sync ordered by `updatedAt` ascending (inclusive). A key restricted to workflows or folders lists only the rules of workflows inside its allowlist; rules for every workflow (`workflowId: null`) are omitted for it.

**Query parameters** (an unknown parameter is a 422 `validation_failed` with `errors[].code = "unknown_parameter"`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowId` | string (uuid) | no |  |
| `enabled` | boolean | no |  |
| `updatedSince` | string (date-time) | no | Incremental sync: only items whose `updatedAt` is at or after this instant (inclusive), ordered by `updatedAt` ascending; an explicit conflicting `sort` / `order` is a 422. Overlap by a minute and dedupe: a Run by `(id, revision)`, any other item (workflow, view, webhook, schedule, automation rule) by `(id, updatedAt)` — a higher `revision` or a later `updatedAt` replaces the copy you hold, an equal one is unchanged. |
| `limit` | integer | no |  |
| `cursor` | string | no | The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [AutomationRuleList](https://developers.processcart.com/reference/schemas#automationrulelist) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "f95bfa64-fea6-421b-9b04-a8d262cf2098",
      "workflowId": "ba1de1e7-01ae-498d-8686-e7b67809372c",
      "workflow": {
        "id": "ba1de1e7-01ae-498d-8686-e7b67809372c",
        "name": "Order fulfillment"
      },
      "name": "Flag large orders",
      "triggerEvent": "task.completed",
      "filter": {
        "taskKey": "details"
      },
      "conditions": {
        "combinator": "and",
        "items": [
          {
            "type": "field",
            "fieldKey": "amount",
            "op": "greater",
            "value": 1000
          }
        ]
      },
      "actions": [
        {
          "type": "add_labels",
          "labelIds": [
            "rush"
          ]
        },
        {
          "type": "set_priority",
          "priority": "high"
        }
      ],
      "enabled": true,
      "disabledReason": null,
      "disabledAt": null,
      "consecutiveFailures": 0,
      "keyMismatches": [],
      "createdBy": null,
      "createdAt": "2026-10-11T05:27:50.402Z",
      "updatedAt": "2026-10-11T05:27:50.402Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```


## POST /v1/automation-rules
**Create an automation rule.** Scope `rules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `createAutomationRule` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/POST/v1/automation-rules).

Creates a rule, turned on: when `triggerEvent` happens on a run of `workflowId` (optionally narrowed by `filter` and field `conditions`), the `actions` run in order — set a field, set the status or priority, add or remove labels, assign a task, notify people, or send the event to a webhook. Task and field keys are checked against the workflow's published version; members, groups, labels and webhooks against the workspace. A `set_field` value is checked like a field write, and one outside the field's bounds is refused (422, `errors[].code` `invalid_value`). A workflow in Trash answers 409 `workflow_trashed`. `workflowId: null` makes a rule for every workflow (header actions, `notify` and `call_webhook` only), which needs a key without an allowlist. A workspace holds at most 100 rules that are on. Audited. A key restricted to workflows or folders may use only the rules of workflows inside its allowlist; a rule for every workflow (`workflowId: null`), or one of a workflow outside the allowlist, answers 403 `not_allowed_for_key`.

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Request body** — `application/json`, [AutomationRuleConfig](https://developers.processcart.com/reference/schemas#automationruleconfig)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `workflowId` | [Uuid](https://developers.processcart.com/reference/schemas#uuid) \\| null | yes |  |
| `triggerEvent` | `"run.created"` \\| `"run.updated"` \\| `"run.status_changed"` \\| `"run.completed"` \\| `"task.ready"` \\| `"task.assigned"` \\| `"task.completed"` \\| `"task.uncompleted"` \\| … | yes |  |
| `filter` | [RuleFilter](https://developers.processcart.com/reference/schemas#rulefilter) | no |  |
| `conditions` | [RuleConditions](https://developers.processcart.com/reference/schemas#ruleconditions) | no |  |
| `actions` | [RuleAction](https://developers.processcart.com/reference/schemas#ruleaction)[] | yes |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 201 | Created. `Location` names the new resource. | [AutomationRule](https://developers.processcart.com/reference/schemas#automationrule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `workflow_not_published` — Workflow not published; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`workflow_not_published`](https://developers.processcart.com/errors#workflow_not_published) — Workflow not published
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "name": "Flag large orders",
  "workflowId": "ba1de1e7-01ae-498d-8686-e7b67809372c",
  "triggerEvent": "task.completed",
  "filter": {
    "taskKey": "details"
  },
  "conditions": {
    "combinator": "and",
    "items": [
      {
        "type": "field",
        "fieldKey": "amount",
        "op": "greater",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "add_labels",
      "labelIds": [
        "rush"
      ]
    },
    {
      "type": "set_priority",
      "priority": "high"
    }
  ]
}
```

**Example response** (201)

```json
{
  "id": "f95bfa64-fea6-421b-9b04-a8d262cf2098",
  "workflowId": "ba1de1e7-01ae-498d-8686-e7b67809372c",
  "workflow": {
    "id": "ba1de1e7-01ae-498d-8686-e7b67809372c",
    "name": "Order fulfillment"
  },
  "name": "Flag large orders",
  "triggerEvent": "task.completed",
  "filter": {
    "taskKey": "details"
  },
  "conditions": {
    "combinator": "and",
    "items": [
      {
        "type": "field",
        "fieldKey": "amount",
        "op": "greater",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "add_labels",
      "labelIds": [
        "rush"
      ]
    },
    {
      "type": "set_priority",
      "priority": "high"
    }
  ],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "keyMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.402Z",
  "updatedAt": "2026-10-11T05:27:50.402Z"
}
```


## GET /v1/automation-rules/{id}
**Get an automation rule.** Scope `rules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it). Operation id `getAutomationRule` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/GET/v1/automation-rules/{id}).

Returns one rule with its trigger, filter, conditions, actions, enabled state and disable reason, failure counter (the rule turns itself off after 10 failed executions in a row), and any keys the published workflow or the workspace no longer has. A key restricted to workflows or folders may use only the rules of workflows inside its allowlist; a rule for every workflow (`workflowId: null`), or one of a workflow outside the allowlist, answers 403 `not_allowed_for_key`.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [AutomationRule](https://developers.processcart.com/reference/schemas#automationrule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "f95bfa64-fea6-421b-9b04-a8d262cf2098",
  "workflowId": "ba1de1e7-01ae-498d-8686-e7b67809372c",
  "workflow": {
    "id": "ba1de1e7-01ae-498d-8686-e7b67809372c",
    "name": "Order fulfillment"
  },
  "name": "Flag large orders",
  "triggerEvent": "task.completed",
  "filter": {
    "taskKey": "details"
  },
  "conditions": {
    "combinator": "and",
    "items": [
      {
        "type": "field",
        "fieldKey": "amount",
        "op": "greater",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "add_labels",
      "labelIds": [
        "rush"
      ]
    },
    {
      "type": "set_priority",
      "priority": "high"
    }
  ],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "keyMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.402Z",
  "updatedAt": "2026-10-11T05:27:50.402Z"
}
```


## PATCH /v1/automation-rules/{id}
**Update an automation rule.** Scope `rules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `updateAutomationRule` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/PATCH/v1/automation-rules/{id}).

Changes any subset of `name`, `workflowId`, `triggerEvent`, `filter`, `conditions` and `actions`; the result is checked as a whole, like a create (a workflow in Trash answers 409 `workflow_trashed`), and the failure counter resets. `enabled` is not part of the configuration — use the enable and disable operations (422 `unknown_key` on `enabled`). Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Request body** — `application/json`, [AutomationRulePatch](https://developers.processcart.com/reference/schemas#automationrulepatch)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `workflowId` | [Uuid](https://developers.processcart.com/reference/schemas#uuid) \\| null | no |  |
| `triggerEvent` | `"run.created"` \\| `"run.updated"` \\| `"run.status_changed"` \\| `"run.completed"` \\| `"task.ready"` \\| `"task.assigned"` \\| `"task.completed"` \\| `"task.uncompleted"` \\| … | no |  |
| `filter` | [RuleFilter](https://developers.processcart.com/reference/schemas#rulefilter) | no |  |
| `conditions` | [RuleConditions](https://developers.processcart.com/reference/schemas#ruleconditions) | no |  |
| `actions` | [RuleAction](https://developers.processcart.com/reference/schemas#ruleaction)[] | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [AutomationRule](https://developers.processcart.com/reference/schemas#automationrule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `workflow_not_published` — Workflow not published; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`workflow_not_published`](https://developers.processcart.com/errors#workflow_not_published) — Workflow not published
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "name": "Flag large orders (over 1,000)"
}
```

**Example response** (200)

```json
{
  "id": "f95bfa64-fea6-421b-9b04-a8d262cf2098",
  "workflowId": "ba1de1e7-01ae-498d-8686-e7b67809372c",
  "workflow": {
    "id": "ba1de1e7-01ae-498d-8686-e7b67809372c",
    "name": "Order fulfillment"
  },
  "name": "Flag large orders (over 1,000)",
  "triggerEvent": "task.completed",
  "filter": {
    "taskKey": "details"
  },
  "conditions": {
    "combinator": "and",
    "items": [
      {
        "type": "field",
        "fieldKey": "amount",
        "op": "greater",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "add_labels",
      "labelIds": [
        "rush"
      ]
    },
    {
      "type": "set_priority",
      "priority": "high"
    }
  ],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "keyMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.402Z",
  "updatedAt": "2026-10-11T05:27:57.211Z"
}
```


## DELETE /v1/automation-rules/{id}
**Delete an automation rule.** Scope `rules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `deleteAutomationRule` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/DELETE/v1/automation-rules/{id}).

Deletes the rule and its execution history. Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 204 | Done; no body. | — |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable


## POST /v1/automation-rules/{id}/enable
**Turn an automation rule on.** Scope `rules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `enableAutomationRule` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/POST/v1/automation-rules/{id}/enable).

Turns the rule on and resets its failure counter — also the way back after it turned itself off (after 10 failed executions in a row, or the loop guard). A workspace holds at most 100 rules that are on (422, `errors[].code` `limit_reached`). A rule whose workflow is in Trash is refused with 409 `workflow_trashed`. Turning on a rule that is on answers 200 unchanged. Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [AutomationRule](https://developers.processcart.com/reference/schemas#automationrule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "f95bfa64-fea6-421b-9b04-a8d262cf2098",
  "workflowId": "ba1de1e7-01ae-498d-8686-e7b67809372c",
  "workflow": {
    "id": "ba1de1e7-01ae-498d-8686-e7b67809372c",
    "name": "Order fulfillment"
  },
  "name": "Flag large orders (over 1,000)",
  "triggerEvent": "task.completed",
  "filter": {
    "taskKey": "details"
  },
  "conditions": {
    "combinator": "and",
    "items": [
      {
        "type": "field",
        "fieldKey": "amount",
        "op": "greater",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "add_labels",
      "labelIds": [
        "rush"
      ]
    },
    {
      "type": "set_priority",
      "priority": "high"
    }
  ],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "keyMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.402Z",
  "updatedAt": "2026-10-11T05:27:58.667Z"
}
```


## POST /v1/automation-rules/{id}/disable
**Turn an automation rule off.** Scope `rules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `disableAutomationRule` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/POST/v1/automation-rules/{id}/disable).

Turns the rule off (reason `manual`); events that happen while it is off are not queued for it. Turning off a rule that is off answers 200 unchanged. Audited.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [AutomationRule](https://developers.processcart.com/reference/schemas#automationrule) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "f95bfa64-fea6-421b-9b04-a8d262cf2098",
  "workflowId": "ba1de1e7-01ae-498d-8686-e7b67809372c",
  "workflow": {
    "id": "ba1de1e7-01ae-498d-8686-e7b67809372c",
    "name": "Order fulfillment"
  },
  "name": "Flag large orders (over 1,000)",
  "triggerEvent": "task.completed",
  "filter": {
    "taskKey": "details"
  },
  "conditions": {
    "combinator": "and",
    "items": [
      {
        "type": "field",
        "fieldKey": "amount",
        "op": "greater",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "add_labels",
      "labelIds": [
        "rush"
      ]
    },
    {
      "type": "set_priority",
      "priority": "high"
    }
  ],
  "enabled": false,
  "disabledReason": "manual",
  "disabledAt": "2026-10-11T05:27:57.496Z",
  "consecutiveFailures": 0,
  "keyMismatches": [],
  "createdBy": null,
  "createdAt": "2026-10-11T05:27:50.402Z",
  "updatedAt": "2026-10-11T05:27:57.894Z"
}
```


## GET /v1/automation-rules/{id}/executions
**List a rule's executions.** Scope `rules:manage` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · paginated (`{ data, nextCursor, hasMore }`). Operation id `listAutomationRuleExecutions` · [open in the API reference](https://developers.processcart.com/reference#tag/automation-rules/GET/v1/automation-rules/{id}/executions).

The rule's execution history, newest first: one execution per matched event, with its status (`queued`, `running`, `done`, `failed`), each action's outcome (`ok`, `skipped`, `failed`) and the error. Filter by `status`. Executions older than 30 days are gone.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Query parameters** (an unknown parameter is a 422 `validation_failed` with `errors[].code = "unknown_parameter"`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"queued"` \\| `"running"` \\| `"done"` \\| `"failed"` | no |  |
| `limit` | integer | no |  |
| `cursor` | string | no | The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [RuleExecutionList](https://developers.processcart.com/reference/schemas#ruleexecutionlist) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "716f9d9d-761b-4292-a371-12c836633430",
      "ruleId": "f95bfa64-fea6-421b-9b04-a8d262cf2098",
      "runId": "498bf18e-e9c2-421c-aba7-101c8d88b7d0",
      "run": {
        "id": "498bf18e-e9c2-421c-aba7-101c8d88b7d0",
        "name": "Order 1042"
      },
      "eventId": "evt_5e687bca-29e2-4089-bd89-deca38ed741b",
      "eventType": "task.completed",
      "status": "done",
      "result": [
        {
          "ok": true,
          "action": "add_labels",
          "detail": "Added labels.",
          "outcome": "ok"
        },
        {
          "ok": true,
          "action": "set_priority",
          "detail": "Set priority to “High”.",
          "outcome": "ok"
        }
      ],
      "error": null,
      "createdAt": "2026-10-11T05:27:52.935Z",
      "startedAt": "2026-10-11T05:27:53.283Z",
      "finishedAt": "2026-10-11T05:27:55.033Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```