Triggers

Make a trigger: which events fire it, a filter, where the event goes

The user's triggers — Roma delivering an event to an outside agent the moment something changes on their lists — in one tool: action list, create, update or delete. A trigger names which events fire it, a filter, and where the event goes: transport webhook POSTs a signed envelope ({ eventId, name, timestamp, text, data, cursor }; Standard Webhooks headers webhook-id, webhook-timestamp, webhook-signature over id.timestamp.body with the secret) to url, which must be https and public (no challenge: a Claude scheduled task's Fire URL with its bearer in headers works as is), the secret answered once on create; transport poll needs no address: the agent reads its deliveries at GET /api/v1/triggers/{id}/deliveries?wait=25&after=<cursor> with its key. data carries the item as get_item returns it, changes with from and to per field, and the actor. Retries at 1 minute, 1 hour and 6 hours, then the trigger is disabled as failing; update with paused: false or a new url brings it back. Pass agentName, the name you post under with post_chat_message: the person's reply to one of your posts then fires the trigger too, and the chat offers them Reply. The transport never changes on update: delete and create again. Twenty per account. list answers the triggers with each one's last delivery and the catalogue of events: item.created (an item was created on one of the person's lists: a task, a note, a row); item.updated (an item's title, due date, reminder, a property value or its archived flag changed); item.statusUpdated (a task's status changed (todo, inprogress, completed)); item.moved (an item moved onto another list); item.deleted (an item was deleted into the trash (recoverable for 30 days)); item.restored (an item came back from the trash); list.created (a list was created); list.updated (a list's name, icon, instructions, properties or archived flag changed); list.deleted (a list was deleted into the trash); list.restored (a list came back from the trash); item.assigned (the person assigned an item to an agent: a person property of the item gained the agent's record (data); message.posted (the person replied to an agent's post in an item's chat (reply on its row; data); automation.completed (an automation's run finished (`data).

post/api/v1/triggers

Request

  • Base URL
    https://api.roma.app
  • URL
    https://api.roma.app/api/v1/triggers
  • Auth
    HTTP bearer

Request body

triggerIdstring

For update and delete: the trigger's id (from list).

namestring

For create (required) or update: what it wakes: "Claude Code on the Mac", "Codex for testing".

eventsstring[]

For create (required) or update: which events fire it.

transport'webhook' | 'poll'

For create: webhook (default, needs url) or poll (no address; read with the deliveries route).

urlstring uri

For a webhook: the https address Roma POSTs to (create), or the new one (update).

secretstring

For a webhook on create: your own whsec_ secret (base64, 32 bytes); minted when absent.

headersobject

For a webhook: extra request headers on every POST, e.g. { "Authorization": "Bearer …" } for a Claude Routine fire URL. Stored, never read back; on update they replace the old ones.

agentNamestring

The agent this trigger wakes, exactly as you name yourself in post_chat_message ("Claude Code"). The person's replies to your posts fire this trigger too. On update, empty clears it.

agentIdstring

The agent RECORD this trigger wakes (one of the person's agents, register_agent): its assignments (item.assigned) and the replies to its posts fire it. On update, empty clears it.

pausedboolean

For update: true pauses, false resumes.

Response

Created; the body is the new item.

secretstring nullable

For create: the signing secret, this once; null for a poll trigger.

deletedboolean

For delete.

Changes

No recorded changes to this operation across all 1 revision of this API.