Forum automation

An automation is a rule that watches your community and acts on its own: tag a topic that mentions a keyword, close one that has gone quiet, welcome a new member with a message, post to a chat channel when an incident opens. Each rule has one trigger, up to twenty conditions that must all match, and one action. This page covers how to write one, what you can trigger on and do, and how to fire a rule from your own systems.

All of these routes need forum.moderate, the capability that lets a person do these things by hand. A personal access token that carries it is how an external system authenticates.

Create a rule

POST /orgs/{orgId}/forum-automations
{
  "name": "Tag billing questions",
  "spaceId": null,
  "trigger": "topic.created",
  "conditions": [
    { "field": "title", "op": "contains", "value": "invoice" }
  ],
  "action": "add_tag",
  "config": { "tags": ["billing"] }
}

A condition is { field, op, value }. The operators are eq, neq, contains, not_contains, has, not_has, lt and gte. Topic fields are title, body, kind, category, tags and tagCount. Depending on the event you can also test userId, trustLevel, isNewUser, isFirstTopicOrPost, userGroups, emailDomain, groupId, postAuthorId, isReply and hasLink. A condition on a field the event does not carry simply does not match.

Triggers

topic.stalled waits for a quiet period set by config.stalledHours (default 72, between 1 and 8760), and stalled topics are looked for once an hour. recurring and point_in_time rules are swept every ten minutes, so expect them to fire within that window rather than to the second. Status triggers carry no topic, so use them with notify, send_webhook or send_chat_message.

Actions

Unknown triggers or actions are refused with a 422.

Run history and management

When a rule does not seem to fire, read its runs first: a skipped run with the detail conditions not met means the event arrived and a condition failed.

Fire a rule from your own system

A rule with the api_call trigger runs only when something calls it:

POST /orgs/{orgId}/forum-automations/{id}/invoke
{ "payload": { "userId": "…", "reason": "chargeback" } }

The payload becomes the context the rule's conditions and action read, so a suspend_user rule can take its userId from the call. The response is the run, with its status and detail. Invoking a rule whose trigger is anything other than api_call is refused; this route cannot be used to fire an event-driven rule out of band.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go clients are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP call_api tool. Where a CLI command or MCP tool exists too, the last column names it. Operation names link to the API reference.

Automation