Account Events API

Account-wide events and the triggers that fire flows or agents in response to them.

10 endpoints

Endpoints

POST

/api/v1/accountEvents/raise

Raise a custom account event; every "On event" trigger on it (a flow, an AI agent, a function) runs

Parameters

`name`	stringrequired	Your own event name, e.g. order_ready (recorded as custom.order_ready)
`subject`	object	What it is about
`properties`	object	Details (up to 30 keys, 8 KB)
`idempotencyKey`	string	Makes retries safe: the same key never records twice

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/raise \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "subject": {},
  "properties": {}
}'

POST

/api/v1/accountEvents/listEventTriggers

The "On event" triggers of this account — "when <event> happens → run <flow | AI agent | function>": event pattern (a name, source.* or *), conditions, target with its name, on/off, last fired, fire count. Params: targetKind?, targetRef? to list one flow's, agent's or function's triggers.

Parameters

`targetKind`	string
`targetRef`	string

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/listEventTriggers \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "targetKind": "example",
  "targetRef": "example"
}'

POST

/api/v1/accountEvents/addEventTrigger

Add an "On event" trigger: the event starts a flow, an AI agent or a function

Parameters

`name`	string	A label; made from the event and target when omitted
`event`	stringrequired	An event name (base.row_created), a source pattern (base.) or for everything
`filters`	array	Only when every filter matches the event properties (subject.name, name, source, origin are also addressable)
`targetKind`	stringrequired	flow \| agent \| account_function \| site_function (a function of one of your sites, by its id; only where switched on)
`targetRef`	stringrequired	flow id \| agent id \| account function id \| site function id
`config`	object

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/addEventTrigger \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "event": "example",
  "filters": {}
}'

POST

/api/v1/accountEvents/updateEventTrigger

Change an "On event" trigger: its event, conditions, name, or on/off

Parameters

`id`	stringrequired
`name`	string
`event`	string
`isActive`	boolean
`filters`	array
`config`	object

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/updateEventTrigger \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "event": "example"
}'

POST

/api/v1/accountEvents/removeEventTrigger

Remove an "On event" trigger

Parameters

id stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/removeEventTrigger \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example"
}'

POST

/api/v1/accountEvents/eventTriggerRuns

What "On event" triggers did: newest first, status queued | ok | failed | skipped with the reason, attempts, the event. Params: triggerId?, limit?.

Parameters

`triggerId`	string
`limit`	integer

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/eventTriggerRuns \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "triggerId": "example",
  "limit": {}
}'

POST

/api/v1/accountEvents/appEventInstalls

The apps installed in this workspace a trigger on this app event (app.<name>) can be for, and the one picked by itself

Parameters

event stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/appEventInstalls \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "example"
}'

POST

/api/v1/accountEvents/appEvents

The events the apps installed in this workspace have sent lately, grouped by app (installId, appName, event names). Use it to see which app.<name> events exist before adding a trigger on one. Params: none.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/appEvents \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

POST

/api/v1/accountEvents/setFlowEventTrigger

Bind a flow's Event Trigger node to an event (upsert)

Parameters

`flowId`	stringrequired
`triggerId`	stringrequired
`event`	stringrequired
`filters`	array
`installId`	string	For one installed app's event (app.<name>): which install. Picked by itself when only one app is installed (or this event came from one); needed otherwise

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/setFlowEventTrigger \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "flowId": "example",
  "triggerId": "example",
  "event": "example"
}'

POST

/api/v1/accountEvents/builtins

Every built-in account event name with its plain-language description, grouped by source: base (rows written by ANY lane: grid, chat, agent, MCP, API, flow, import), drive, site, flow, agent, function, email, journey, marketplace, billing, connector, channel. Your own events are custom.<name>. Use it before adding an "On event" trigger. There is no event log: what a trigger did is on the trigger (accountEvents_eventTriggerRuns).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/accountEvents/builtins \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'