Chain Triggers

A Chain is an executable workflow: its Bit-DAG is the action. A chain trigger declares when that workflow runs. One chain may have many triggers (e.g. a daily cron and an event trigger). Triggers replace the removed legacy automation rules free-text form — you connect existing Agents/Twins/Chains as Bit nodes instead of typing prompts.

Every trigger fires through the loop-guarded run path, so cron, event, and chain→chain firings are wallet-reserved and protected against runaway recursion.

Trigger types

trigger_type	Fires when	triggerConfig
manual	A user calls POST /chains/:id/trigger-run	—
cron	A 5-field cron expression matches (minute granularity)	{ "cron": "0 9 * * 1" }
event	A subscribed domain event is emitted	{ "eventType": "chain.streak_broken" }

Specialized legacy event types (bit_overdue, chain_streak_broken, period_completed, …) all map to event + the corresponding eventType.

Endpoints

Method	Path	Description	Auth	Rate Limit
POST	/chains/:chainId/triggers	Create a trigger	JWT	30/min
GET	/chains/:chainId/triggers	List a chain's triggers	JWT	60/min
PATCH	/chains/:chainId/triggers/:triggerId	Update a trigger (re-runs loop validation)	JWT	30/min
POST	/chains/:chainId/triggers/:triggerId/deactivate	Deactivate a trigger	JWT	30/min

Create a trigger

Request

POST /chains/{chainId}/triggers
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "trigger_type": "cron",
  "triggerConfig": { "cron": "0 9 * * 1" },
  "conditions": [
    { "field": "bit.priority", "operator": "gte", "value": 3 }
  ],
  "cooldownMinutes": 60,
  "maxRunsPerDay": 5,
  "scheduleId": null,
  "isActive": true
}

Tenant fields (account/chainer/workspace) are derived from the owning chain and must not be sent. conditions use the structured {field, operator, value} shape (operators: eq, neq, gt, gte, lt, lte, contains, exists); all conditions must pass (AND). There is no free-text actions/prompt field — the chain's Bit-DAG is the action.

Validation

• cron triggers require triggerConfig.cron; event triggers require triggerConfig.eventType (400 otherwise).
• An event trigger that listens on the chain or bit entity family (which a chain run inevitably affects) is rejected as a self-loop with 422 and code automation_rule_cycle.
• Event triggers get pacing defaults applied: cooldownMinutes >= 1 and a maxRunsPerDay default so a hot event cannot fan out unbounded.

Response

{
  "data": {
    "id": "…",
    "chainId": "…",
    "triggerType": "cron",
    "triggerConfig": { "cron": "0 9 * * 1" },
    "conditions": [],
    "isActive": true,
    "cooldownMinutes": 60,
    "maxRunsPerDay": 5,
    "scheduleId": null,
    "runCount": "0",
    "lastTriggeredAt": null,
    "lastStatus": null,
    "createdAt": "…",
    "updatedAt": "…"
  }
}

See also

• Chains API — the workflow entity itself.
• Chain Execution Policy — agent mode + the Bit-tree DAG.