Skip to main content
POST
Propose an automation rule

The propose → confirm flow

Every write to an automation rule goes through two calls: a propose that validates the change, previews it and returns a single-use proposal_token, and a confirm that sends the token back and applies exactly what was previewed, nothing else. The propose call writes nothing. This section walks through one round trip for a new rule; the edit pair (propose, confirm) and the reorder pair (propose, confirm) follow the same shape. Every call in this group needs an administrator token. A person turns rules on and off. A rule created through the API is always created off, and active in a payload is refused with a 422. Turning a rule on, or off, is done by someone in the Cloud Chat automations screen. The same idea covers edits: only a rule that is off can be edited through the API. To change a rule that is running, propose a new rule with the change, and let a person turn the new one on and the old one off. Rules with a non-null managed_by are kept in sync by the ClaudIA integration. They can be read, but the API refuses to edit them (403) and a new order must keep them where they are.

1. Propose

Send the rule under automation_rule. name, event_name, conditions and actions are required, in the same shape getAutomationRule returns them.
Request
The response previews the rule as it will be saved, and nothing is written yet:
Response

2. Review the warnings

warnings lists risks the change carries, so whoever confirms does it knowingly. They never block the confirm. Each one has a stable code, a severity (high or medium), a localized message, and the rule_ids of the other rules involved. Branch on code, never on message. If the preview or a warning shows something you did not intend, discard the token and propose again.

3. Confirm

Send back only the proposal_token, before expires_at. No other body field is read: the server applies the proposal it stored.
Request
The 201 response carries the saved rule, still off, in the same shape getAutomationRule returns. The token works once, only for the user who proposed, and only on the account it was issued for. A reused, expired or foreign token answers 400 invalid_proposal. A confirm also answers 409 stale_proposal when the rules it depends on changed after the proposal: for a create or a reorder, any rule of the same event; for an edit, the rule itself, for example someone edited it in the screen. Nothing is written in either case: read the rules again and propose again.

Authorizations

Authorization
string
header
required

The id_token from POST /auth/v1/signin, sent as Authorization: Bearer <id_token>. Not the access_token — that one does not carry the identity Cloud Chat authorizes on.

Headers

cloudchat-instance
integer
required

Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.

Example:

1

Path Parameters

accountId
integer
required

Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.

Example:

1

Body

application/json
automation_rule
object
required

The new rule. name, event_name, conditions and actions are required.

Response

The proposal. Nothing was written.

proposal_token
string
required

Single-use token for the matching confirm call. It is tied to this account and to the user who proposed, and it stops working at expires_at.

Example:

"eyJfcmFpbHMiOnsiZGF0YSI6eyJqdGkiOiI0YjEw..."

expires_at
string<date-time>
required

When the token stops working. Read it from here instead of assuming a fixed lifetime.

Example:

"2026-11-12T14:20:00Z"

kind
enum<string>
required
Available options:
create
Example:

"create"

automation_rule
object
required

The rule as it will be created. It has no id yet.

warnings
object[]
required

Risks detected in the proposal. Empty when nothing was found.