> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/functions/triggers.md).

# Triggers

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="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### List Triggers

Supports filtering by active/paused state and continuation-token pagination.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Get Trigger

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers/{trigger\_id}" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% 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="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers/{trigger\_id}" method="put" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Delete Trigger

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers/{trigger\_id}" method="delete" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% 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="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers/{trigger\_id}/pause" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% 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="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers/{trigger\_id}/resume" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% 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="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers/{trigger\_id}/fire" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% 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="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/triggers/{trigger\_id}/runs" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% 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.

## External System to Outbound Call

A common integration pattern is triggering an outbound voice call when an external system sends a lead or event notification. Here is how to wire it up end-to-end.

### 1. Identify a compatible action skill

Obtain the ID of a skill whose stored action configuration selects `action_type: "schedule_outbound_call"`. This deterministic action shape must already be provisioned; the current public skill-create schema and Go CLI create standard companion skills rather than accepting an arbitrary `action_type` configuration.

The object a trigger dispatches is a Skill: the trigger's `action_id` field holds the skill ID, and the `action_type` key in the skill's configuration selects the skill's dispatch behavior.

The `action_type` field tells the platform to use the deterministic outbound path - no LLM reasoning loop, just direct task creation. This is faster, cheaper, and produces consistent results.

### 2. Create a trigger bound to the skill

```bash
forge platform triggers create \
  --body '{
    "name": "outbound-intake-call",
    "event_type": "amigo.trigger.cron",
    "action_id": "<skill_id>",
    "input_template": {"phone_to": ""},
    "timezone": "UTC"
  }'
```

The `input_template` defines the shape of the input the action expects. At fire time, values supplied in the fire request's `input` override are merged into this template.

### 3. Fire the trigger from the external system

Have the external system call the Fire Trigger endpoint directly, authenticating with a workspace API key and passing the dynamic values in the `input` override body:

```bash
curl -X POST "https://api.platform.amigo.ai/v1/{workspace_id}/triggers/{trigger_id}/fire" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "phone_to": "+15551234567"
    }
  }'
```

The `input` object overrides matching keys in the trigger's stored `input_template`, so the caller maps its own payload fields (for example, a CRM's `contact.phone`) to the trigger input keys before sending the request. The same fire can be issued from the CLI:

```bash
forge platform triggers fire "<trigger_id>" \
  --body '{"input":{"phone_to":"+15551234567"}}'
```

### What happens after the fire

The fire request returns a `fired_event_id`; the action run, world-model projection, and call lifecycle continue asynchronously:

* The deterministic action writes an `outbound.scheduled` task with the configured schedule, priority, business-hours window, and retry fields.
* A stable fire identifier and task identity reduce duplicate task creation. They do not make downstream telephony delivery exactly once.
* A linked `patient_entity_id` gives the runtime an identity anchor; actual context loading still depends on the selected service, runtime, permissions, and projected data.
* If a call attempt reports a retriable failure and attempts remain, the dispatcher can schedule another attempt with the configured backoff. Exhausted attempts project a failed task state.
* Trigger-run status, task projection, call acceptance, and terminal call outcome are separate milestones and can each be missing or delayed if their path fails.

### Input fields for outbound actions

When `action_type` is `schedule_outbound_call`, the merged input (template + fire-time `input` override) accepts:

| Field                   | Type              | Required  | Description                                                                        |
| ----------------------- | ----------------- | --------- | ---------------------------------------------------------------------------------- |
| `phone_to`              | string (E.164)    | Yes       | Destination phone number                                                           |
| `reason`                | string            | No        | Why the call is being made (default: `outbound_intake`)                            |
| `goal`                  | string            | No        | What the agent should accomplish (default: `Complete the requested outbound call`) |
| `priority`              | integer (1-10)    | No        | Dispatch priority, higher = first (default: 8)                                     |
| `max_attempts`          | integer (1-10)    | No        | Maximum call attempts (default: 3)                                                 |
| `retry_backoff_minutes` | integer (1-1440)  | No        | Minutes between retries (default: 30)                                              |
| `window`                | object            | No        | Business hours constraint (default: 09:00-18:00 America/New\_York)                 |
| `scheduled_at`          | string (ISO 8601) | No        | When the call should be placed (default: now)                                      |
| `service_id`            | string (UUID)     | See below | Specific agent service to handle the call                                          |
| `patient_entity_id`     | string (UUID)     | No        | Link to existing patient entity for context loading                                |
| `phone_from`            | string (E.164)    | See below | Caller ID override                                                                 |
| `context`               | object            | No        | Free-form context passed through to the call task                                  |

At least one of `service_id` or `phone_from` is required so the platform can route the call; the fire fails with a validation error when both are absent.

### Tracing a fire through the system

When each stage succeeds, a trigger-driven outbound task can produce this trace:

1. **`trigger.fired`** - The trigger was activated
2. **`outbound.scheduled`** - The outbound task was created with all scheduling parameters
3. **`trigger.completed`** - The action finished (includes `duration_ms`, `events_written`)
4. **`outbound.dispatched`** - The call was placed (includes `call_sid`)
5. **`outbound.completed`** or **`outbound.failed`** - Final outcome

Query available events through world-model event queries or the analytics layer. The trigger's execution history endpoint returns durable run records linked to their originating fire through `fired_event_id`. Do not infer a missing stage from the presence of a later one without checking the relevant run, task, and call records.

## 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.amigo.ai/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/functions/triggers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.