# Update rule

Pause an automation you manage. To create, resume or test an automation, use Brigg: it runs with its owner’s permissions after the current API call has ended.

POST https://api.brigg.app/v1/operations/automation.UpdateRule

## Access & visibility

Allow `automation.UpdateRule` on your API key.

**Acting member required.** Send `Brigg-Act-As` with an [approved member account ID](https://developer.brigg.app/authentication#member-delegation). The key supplies permissions; the member selects whose data is used.

The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.

[Set up authentication](https://developer.brigg.app/authentication) · [Choose permissions](https://developer.brigg.app/permissions)

## Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rule_id` | string | Yes | Use the returned rule_id together with its app_id. A rule's display label is not its ID. [automation.ListRules](https://developer.brigg.app/reference/automation/ListRules). At least 1 character. |
| `app_id` | string | No | Use the owning app's app_id from ListApps, or core for workspace-native automations. This is not a public operation namespace. Omit only when the request field is optional. [workspace.ListApps](https://developer.brigg.app/reference/workspace/ListApps). |
| `enabled` | boolean | Yes | Pause an automation. Creation, resumption and test execution require a person in Brigg because a rule runs later with its owner's permissions. Always `false`. |

## Inspect before changing an automation

Find a rule with [List rules](https://developer.brigg.app/reference/automation/ListRules), then read [Get rule](https://developer.brigg.app/reference/automation/GetRule) for its current configuration and recent runs. Preserve the `rule_id` and `app_id` pair. `enabled` controls future trigger handling; it is not a report that an earlier run succeeded.

Check `can_manage` before offering an edit or delete action. Built-in locked rules may be visible without being editable. The public update can pause a rule with enabled: false. It cannot resume a rule or author new actions; perform those steps in Brigg.

## Response

Returns **200 OK** with a JSON body.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rule_id` | string | Yes | Rule identifier. |
| `app_id` | string | Yes | App identifier. |
| `rule` | [object](#response-rule) or null | Yes | The definition AS STORED. |
| `enabled` | boolean | Yes | Whether this feature is enabled. |

### response.rule

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rule_id` | string | Yes | Rule identifier. |
| `app_id` | string | Yes | App identifier. |
| `description` | string or null | No | Descriptive text. |
| `trigger` | [object](#response-rule-trigger) | No | Condition or schedule that starts the automation. |
| `enabled` | boolean | Yes | Whether this feature is enabled. |
| `locked` | boolean | Yes | Built-in: neither disabled nor deleted. |
| `scope` | string | Yes | `org` for an org-level rule, `mine` for the caller's own. |
| `can_manage` | boolean | Yes | Whether the acting member can manage this automation. |
| `created_at` | number | Yes | Creation time in Unix milliseconds. |

### response.rule.trigger

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | Type identifying which variant of this model applies. Allowed: `"on_cron"`, `"on_create"`, `"on_update"`, `"on_delete"`, `"on_message"`. |
| `schedule` | string | No | Cron expression for an on_cron trigger, typically minute hour day-of-month month day-of-week. For example, 0 9 * * 1-5 runs at 09:00 on weekdays in timezone. Not present on record-change triggers. |
| `timezone` | string | No | IANA time zone, for example Europe/Oslo. |
| `resource_type` | string | No | Resource type whose changes can trigger this automation. |
| `fields` | array of string | No | Record fields whose changes the trigger observes. |
| `transition` | [object](#response-rule-trigger-transition) | No | Field-value transition that qualifies a record change. |
| `channel` | string | No | Communication channel to which this trigger applies. |

### response.rule.trigger.transition

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | Yes | Record field whose change the trigger observes. |
| `to` | string or boolean or number | Yes | Destination value that the field must change to. |

## Errors & retries

Set `BRIGG_REQUEST_ID` once for each logical action. The samples send it as `Idempotency-Key`. Reuse the same value and body on retries, including after a timeout; a missing response does not prove the action failed.

For rate limits, follow the server’s retry guidance and back off. See [HTTP errors](https://developer.brigg.app/http#errors) and [safe retries and limits](https://developer.brigg.app/reliability).

| HTTP status | Code | What to do |
| --- | --- | --- |
| 400 | `invalid_json` | Send a JSON object with Content-Type: application/json. |
| 400 | `invalid_input` | Check the request fields and types. Supply a stable Idempotency-Key containing 1–200 characters. |
| 401 | `invalid_key` | The workspace API key is missing, invalid or revoked. |
| 403 | `forbidden` | Check the key’s operation and resource grants. Supply Brigg-Act-As with a member authorized by the key’s delegation grant. The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply. |
| 404 | `not_found` | The requested operation or resource is not available to this credential. |
| 429 | `rate_limited` | Wait for Retry-After before retrying. Reuse the original Idempotency-Key. |

## Next steps

- [List rules](https://developer.brigg.app/reference/automation/ListRules)
- [Get rule](https://developer.brigg.app/reference/automation/GetRule)
- [List apps](https://developer.brigg.app/reference/workspace/ListApps)

[Download OpenAPI](https://developer.brigg.app/openapi.json) · [Versioning & retirement](https://developer.brigg.app/versioning)

## Examples

### Example request

Fictional values. Replace IDs and business details with values from your workspace.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/automation.UpdateRule' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "rule_id": "e_example",
  "enabled": false
}'
```

#### TypeScript


```typescript
const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/automation.UpdateRule", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "rule_id": "e_example",
    "enabled": false
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);
```

#### Python


```python
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "rule_id": "e_example",
  "enabled": False
}
request = Request(
    "https://api.brigg.app/v1/operations/automation.UpdateRule",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise
```

#### Response example


```json
{
  "rule_id": "e_example",
  "app_id": "e_example",
  "rule": null,
  "enabled": true
}
```

## JSON schemas


```json-schema-request
{
  "type": "object",
  "properties": {
    "rule_id": {
      "type": "string",
      "minLength": 1,
      "description": "Use the returned rule_id together with its app_id. A rule's display label is not its ID. [automation.ListRules](https://developer.brigg.app/reference/automation/ListRules)."
    },
    "app_id": {
      "type": "string",
      "description": "Use the owning app's app_id from ListApps, or core for workspace-native automations. This is not a public operation namespace. Omit only when the request field is optional. [workspace.ListApps](https://developer.brigg.app/reference/workspace/ListApps)."
    },
    "enabled": {
      "type": "boolean",
      "const": false,
      "description": "Pause an automation. Creation, resumption and test execution require a person in Brigg because a rule runs later with its owner's permissions."
    }
  },
  "required": [
    "rule_id",
    "enabled"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "rule_id": "e_example",
      "enabled": false
    }
  ]
}
```


```json-schema-response
{
  "type": "object",
  "properties": {
    "rule_id": {
      "type": "string",
      "description": "Rule identifier."
    },
    "app_id": {
      "type": "string",
      "description": "App identifier."
    },
    "rule": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "rule_id": {
          "type": "string",
          "description": "Rule identifier."
        },
        "app_id": {
          "type": "string",
          "description": "App identifier."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Descriptive text."
        },
        "trigger": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "on_cron",
                "on_create",
                "on_update",
                "on_delete",
                "on_message"
              ],
              "description": "Type identifying which variant of this model applies."
            },
            "schedule": {
              "type": "string",
              "description": "Cron expression for an on_cron trigger, typically minute hour day-of-month month day-of-week. For example, 0 9 * * 1-5 runs at 09:00 on weekdays in timezone. Not present on record-change triggers."
            },
            "timezone": {
              "type": "string",
              "description": "IANA time zone, for example Europe/Oslo."
            },
            "resource_type": {
              "type": "string",
              "description": "Resource type whose changes can trigger this automation."
            },
            "fields": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Record fields whose changes the trigger observes."
            },
            "transition": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "Record field whose change the trigger observes."
                },
                "to": {
                  "type": [
                    "string",
                    "boolean",
                    "number"
                  ],
                  "description": "Destination value that the field must change to."
                }
              },
              "required": [
                "field",
                "to"
              ],
              "additionalProperties": false,
              "description": "Field-value transition that qualifies a record change."
            },
            "channel": {
              "type": "string",
              "description": "Communication channel to which this trigger applies."
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false,
          "description": "Condition or schedule that starts the automation."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this feature is enabled."
        },
        "locked": {
          "type": "boolean",
          "description": "Built-in: neither disabled nor deleted."
        },
        "scope": {
          "type": "string",
          "description": "`org` for an org-level rule, `mine` for the caller's own."
        },
        "can_manage": {
          "type": "boolean",
          "description": "Whether the acting member can manage this automation."
        },
        "created_at": {
          "type": "number",
          "description": "Creation time in Unix milliseconds."
        }
      },
      "required": [
        "rule_id",
        "app_id",
        "enabled",
        "locked",
        "scope",
        "can_manage",
        "created_at"
      ],
      "description": "The definition AS STORED.",
      "additionalProperties": false
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether this feature is enabled."
    }
  },
  "required": [
    "rule_id",
    "app_id",
    "rule",
    "enabled"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "rule_id": "e_example",
      "app_id": "e_example",
      "rule": null,
      "enabled": true
    }
  ]
}
```