> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/functions/triggers.md). # Triggers Dispatch workspace actions from cron schedules, matching live events, or authenticated manual fire requests, with durable run history. Triggers bind either a cron schedule or a supported world-event type to a workspace action. A manual fire is also available for authenticated callers. Cron and manual fires record a `trigger.fired` event before queuing a durable action run. Event-based matching queues a run from the original world event instead of creating another `trigger.fired` event. Execution is asynchronous, and the run record exposes status and attempt tracking. {% hint style="info" %} **Use cases**: schedule a nightly outreach action, run a weekly report, react to a supported workspace event, or expose a controlled action fire to an external system. Event matching is live and at most once, so workflows that cannot miss an event need their own durable source and reconciliation path. {% endhint %} ## Endpoints All trigger endpoints are scoped to a workspace: `/v1/{workspace_id}/triggers`. ### Create Trigger Creates a trigger and returns the full trigger object including the computed `next_fire_at`. {% openapi src="" path="/v1/{workspace\_id}/triggers" method="post" %} {% endopenapi %} ### List Triggers Supports filtering by active/paused state and continuation-token pagination. {% openapi src="" path="/v1/{workspace\_id}/triggers" method="get" %} {% endopenapi %} ### Get Trigger {% openapi src="" path="/v1/{workspace\_id}/triggers/{trigger\_id}" method="get" %} {% endopenapi %} ### Update Trigger Accepts any subset of the create fields. The schedule's `next_fire_at` is recomputed when the `schedule` or `timezone` fields change. {% openapi src="" path="/v1/{workspace\_id}/triggers/{trigger\_id}" method="put" %} {% endopenapi %} ### Delete Trigger {% openapi src="" path="/v1/{workspace\_id}/triggers/{trigger\_id}" method="delete" %} {% endopenapi %} ### Pause Trigger Pauses the trigger's schedule. The trigger remains in the workspace but will not fire until resumed. Returns the updated trigger object with `is_active: false`. {% openapi src="" path="/v1/{workspace\_id}/triggers/{trigger\_id}/pause" method="post" %} {% endopenapi %} ### Resume Trigger Resumes a paused trigger. The `next_fire_at` is recomputed from the current time. Returns the updated trigger object with `is_active: true`. {% openapi src="" path="/v1/{workspace\_id}/triggers/{trigger\_id}/resume" method="post" %} {% endopenapi %} ### Fire Trigger (Manual) Records a manual fire and queues the trigger's action regardless of its cron schedule or active state. The response confirms that the fire was accepted, not that the action or any downstream effect completed. The request accepts an optional `input` object. Values from the override are merged into the trigger's stored `input_template` at fire time, with override values taking precedence, so callers can supply dynamic values without modifying the trigger configuration. This is how external systems pass dynamic payload fields through to the action: an API-key-authenticated caller fires the trigger directly with the values it wants to override. {% openapi src="" path="/v1/{workspace\_id}/triggers/{trigger\_id}/fire" method="post" %} {% endopenapi %} ### Execution History Returns the trigger's execution history as a list of durable run records (run ID, fired event ID, source, status, attempt and claim tracking, result text or error, and timestamps), ordered by most recent first. {% openapi src="" path="/v1/{workspace\_id}/triggers/{trigger\_id}/runs" method="get" %} {% endopenapi %} ## Event Types and Schedules Every trigger declares an `event_type` from the API's closed `TriggerableEvent` set. For an event-based trigger (`schedule: null`), it identifies the incoming workspace event to match. The optional `event_filter` applies top-level subset equality to that event's `data`: every configured key must be present with an equal value. It is not a general JSONPath expression. Set `schedule` to a cron expression evaluated in the trigger's `timezone` for a recurring trigger; cron configurations conventionally use `event_type: amigo.trigger.cron`. Omit `schedule` for an event-based trigger or one fired only through the manual endpoint. Event matching considers only active triggers without a schedule. Each accepted cron or manual fire produces a `trigger.fired` record and linked run. When enqueueing succeeds, a matched world event produces at most one run per trigger-event pair and retains the originating event for provenance without emitting a second `trigger.fired` record. ## External Activation External systems can call `POST /v1/{workspace_id}/triggers/{trigger_id}/fire` with a workspace API key and an optional `input` override. The platform records the fire and queues the action run. Poll the trigger's execution history for the action outcome rather than treating the fire response as completion. ## Calls From External Events A trigger action does not place a phone call. To call a patient when an external system sends a lead or event notification, have your integration call the [Outbound Calls API](/developer-guide/platform-api/conversations/calls.md) with the destination, use case, reason, and patient identifier, and apply its own consent, retry, pacing, and business-hours rules. ## Provenance World events produced by trigger actions carry an `AUTOMATION` source tag, distinguishing them from conversation-driven or manual events. For cron and manual fires, `fired_event_id` identifies the `trigger.fired` event linked to the trigger. For event-based runs, it is a stable per-trigger correlation identifier derived from the originating world event rather than the ID of a new `trigger.fired` record. ## CLI Triggers can be managed through Agent Forge: `forge platform triggers create|list|get|update|delete|pause|resume|fire|runs`. See the [Agent Forge reference](https://docs.concurrence.com/reference/agent-forge) for details. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.concurrence.com/developer-guide/platform-api/functions/triggers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.