Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

update_business_rule

Changes a business rule in part and moves it where the lifecycle allows by hand; the review states stay with the approvers.

Change a business rule by business_rule_id with any of name, type (constraint, derivation, computation, inference, action_enabler or policy), statement (HTML), condition, action, exceptions (HTML), examples (replaces the rows of input and expected), authority_stakeholder_id, authority, priority, effective_from, effective_to, owner_id and status. A field left out keeps its value; a field sent as null is cleared. The fields go through the same action the Business Rules page runs and write a version; business_rule.updated goes out. A status goes through its own move: deprecated, baselined or back to draft are moves a person may make by hand, and business_rule.status_changed goes out. in_review and approved are reached through submit_for_review and the approvers, and any move is refused while an approval request is open. A staff token with business-rule:update on the project is needed.

Requires ability

business-rule:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same actions as

PATCH/v1/business-rules/{rule}POST/v1/business-rules/{rule}/status

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires events

business_rule.updatedbusiness_rule.status_changed

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

business_rule_id*string

UUID of the business rule.

namestringoptional

What the rule is called, 3 to 200 characters.

typestringoptional

The kind of rule.

constraintderivationcomputationinferenceaction_enablerpolicy
statementstringoptional

The rule in plain words, as HTML.

conditionstringoptional

When the rule applies.

actionstringoptional

What follows when it does.

exceptionsstringoptional

When it does not apply, as HTML.

examplesarrayoptional

Worked examples replacing the list: objects with input and expected.

authority_stakeholder_idstringoptional

UUID of the stakeholder who may change the rule.

authoritystringoptional

Who or what the rule's authority is, in words.

prioritystringoptional

Its MoSCoW priority.

mustshouldcouldwont
effective_fromstringoptional

When the rule comes into force, YYYY-MM-DD.

effective_tostringoptional

When it stops applying, YYYY-MM-DD.

owner_idstringoptional

UUID of the person who answers for it.

statusstringoptional

A move the lifecycle allows by hand; the review states go through submit_for_review.

draftin_reviewapprovedbaselineddeprecated

What it returns

{  "data": {    "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "number": 4,    "reference": "SCL-BR-4",    "name": "A pickup needs a paid order",    "type": "constraint",    "statement": "<p>A pickup slot can be booked only against an order that is paid in full.</p>",    "condition": "When a pickup is booked",    "action": "the order must be paid in full",    "exceptions": null,    "examples": [      {        "input": "Unpaid order, pickup requested",        "expected": "Refused with a payment link"      }    ],    "authority_stakeholder_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",    "authority_stakeholder_name": "Nadeesha Perera",    "authority": "The shop's credit policy",    "priority": "must",    "effective_from": null,    "effective_to": null,    "status": "draft",    "owner_id": null,    "owner_name": null,    "position": 4,    "version": 2,    "approved_at": null,    "approved_revision_id": null,    "created_at": "2026-10-28T10:40:00+00:00",    "updated_at": "2026-10-28T12:00:00+00:00"  }}

How it fails

VALIDATION_FAILED

a field outside its limits, a type or priority outside its set, an example without an input, a status of in_review or approved (the message says to submit the rule for review), a move the lifecycle does not allow, a move while a request is open, or a stakeholder or owner that is not the project's or the team's.

RESOURCE_NOT_FOUND

unknown business_rule_id, or a rule outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry business-rule:update.

TOKEN_MISSING_ABILITY

token lacks business-rule:update.

Related

get_business_rulethe rule as it stands.propose_business_rulea new one.submit_for_reviewthe road into review and approved.Business rules APIthe same doors over REST.

How is this guide?

Last updated on