Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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.

Create a trigger

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
namestring · min: 1 · max: 256Required
descriptionstring · max: 2000 · nullableOptional
event_typestring · enumRequired

Closed set of world events that trigger definitions may subscribe to.

The database column intentionally remains text for compatibility with old rows, but API writes must choose from this list so typoed event names do not silently create never-matching triggers.

Possible values:
action_idstring · uuidRequired
schedulestring · min: 1 · max: 128 · nullableOptional
timezonestring · min: 1 · max: 64OptionalDefault: UTC
Responses
201

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired

Trigger display name

descriptionstring · nullableOptional

Human-readable description

event_typestringRequired

Event type pattern to match

action_idstring · uuidRequired

Action (skill) to invoke when fired

schedulestring · nullableOptional

Cron schedule expression (e.g. '0 9 * * 1-5')

timezonestringRequired

IANA timezone for schedule evaluation

next_fire_atstring · date-time · nullableOptional

Next scheduled fire time

is_activebooleanRequired

Whether the trigger is active

created_bystring · nullableOptional

Entity ID of the creator

created_atstring · date-time · nullableOptional

When the trigger was created

updated_atstring · date-time · nullableOptional

When the trigger was last updated

post/v1/{workspace_id}/triggers
POST /v1/{workspace_id}/triggers HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 266

{
  "name": "text",
  "description": "text",
  "event_type": "amigo.trigger.cron",
  "event_filter": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "action_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_template": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": "text",
  "timezone": "UTC"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "event_type": "text",
  "event_filter": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "action_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_template": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": "text",
  "timezone": "text",
  "next_fire_at": "2026-01-01T00:00:00.000Z",
  "is_active": true,
  "created_by": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

List Triggers

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

List triggers

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
is_activeboolean · nullableOptional
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/triggers
GET /v1/{workspace_id}/triggers HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "event_type": "text",
      "event_filter": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "action_id": "123e4567-e89b-12d3-a456-426614174000",
      "input_template": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "schedule": "text",
      "timezone": "text",
      "next_fire_at": "2026-01-01T00:00:00.000Z",
      "is_active": true,
      "created_by": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Get Trigger

Get a trigger

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
trigger_idstring · uuidRequired
Responses
200

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired

Trigger display name

descriptionstring · nullableOptional

Human-readable description

event_typestringRequired

Event type pattern to match

action_idstring · uuidRequired

Action (skill) to invoke when fired

schedulestring · nullableOptional

Cron schedule expression (e.g. '0 9 * * 1-5')

timezonestringRequired

IANA timezone for schedule evaluation

next_fire_atstring · date-time · nullableOptional

Next scheduled fire time

is_activebooleanRequired

Whether the trigger is active

created_bystring · nullableOptional

Entity ID of the creator

created_atstring · date-time · nullableOptional

When the trigger was created

updated_atstring · date-time · nullableOptional

When the trigger was last updated

get/v1/{workspace_id}/triggers/{trigger_id}
GET /v1/{workspace_id}/triggers/{trigger_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "event_type": "text",
  "event_filter": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "action_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_template": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": "text",
  "timezone": "text",
  "next_fire_at": "2026-01-01T00:00:00.000Z",
  "is_active": true,
  "created_by": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update Trigger

Accepts any subset of the create fields. The schedule's next_fire_at is recomputed when the schedule or timezone fields change.

Update a trigger

put
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
trigger_idstring · uuidRequired
Body
namestring · min: 1 · max: 256 · nullableOptional
descriptionstring · max: 2000 · nullableOptional
event_typestring · enum · nullableOptional

Closed set of world events that trigger definitions may subscribe to.

The database column intentionally remains text for compatibility with old rows, but API writes must choose from this list so typoed event names do not silently create never-matching triggers.

Possible values:
action_idstring · uuid · nullableOptional
schedulestring · min: 1 · max: 128 · nullableOptional
timezonestring · min: 1 · max: 64 · nullableOptional
Responses
200

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired

Trigger display name

descriptionstring · nullableOptional

Human-readable description

event_typestringRequired

Event type pattern to match

action_idstring · uuidRequired

Action (skill) to invoke when fired

schedulestring · nullableOptional

Cron schedule expression (e.g. '0 9 * * 1-5')

timezonestringRequired

IANA timezone for schedule evaluation

next_fire_atstring · date-time · nullableOptional

Next scheduled fire time

is_activebooleanRequired

Whether the trigger is active

created_bystring · nullableOptional

Entity ID of the creator

created_atstring · date-time · nullableOptional

When the trigger was created

updated_atstring · date-time · nullableOptional

When the trigger was last updated

put/v1/{workspace_id}/triggers/{trigger_id}
PUT /v1/{workspace_id}/triggers/{trigger_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "name": "text",
  "description": "text",
  "event_type": "amigo.trigger.cron",
  "event_filter": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "action_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_template": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": "text",
  "timezone": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "event_type": "text",
  "event_filter": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "action_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_template": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": "text",
  "timezone": "text",
  "next_fire_at": "2026-01-01T00:00:00.000Z",
  "is_active": true,
  "created_by": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Delete Trigger

Delete a trigger

delete
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
trigger_idstring · uuidRequired
Responses
204

Successful Response

No content
delete/v1/{workspace_id}/triggers/{trigger_id}
DELETE /v1/{workspace_id}/triggers/{trigger_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

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.

Pause a trigger

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
trigger_idstring · uuidRequired
Responses
200

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired

Trigger display name

descriptionstring · nullableOptional

Human-readable description

event_typestringRequired

Event type pattern to match

action_idstring · uuidRequired

Action (skill) to invoke when fired

schedulestring · nullableOptional

Cron schedule expression (e.g. '0 9 * * 1-5')

timezonestringRequired

IANA timezone for schedule evaluation

next_fire_atstring · date-time · nullableOptional

Next scheduled fire time

is_activebooleanRequired

Whether the trigger is active

created_bystring · nullableOptional

Entity ID of the creator

created_atstring · date-time · nullableOptional

When the trigger was created

updated_atstring · date-time · nullableOptional

When the trigger was last updated

post/v1/{workspace_id}/triggers/{trigger_id}/pause
POST /v1/{workspace_id}/triggers/{trigger_id}/pause HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "event_type": "text",
  "event_filter": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "action_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_template": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": "text",
  "timezone": "text",
  "next_fire_at": "2026-01-01T00:00:00.000Z",
  "is_active": true,
  "created_by": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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.

Resume a trigger

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
trigger_idstring · uuidRequired
Responses
200

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired

Trigger display name

descriptionstring · nullableOptional

Human-readable description

event_typestringRequired

Event type pattern to match

action_idstring · uuidRequired

Action (skill) to invoke when fired

schedulestring · nullableOptional

Cron schedule expression (e.g. '0 9 * * 1-5')

timezonestringRequired

IANA timezone for schedule evaluation

next_fire_atstring · date-time · nullableOptional

Next scheduled fire time

is_activebooleanRequired

Whether the trigger is active

created_bystring · nullableOptional

Entity ID of the creator

created_atstring · date-time · nullableOptional

When the trigger was created

updated_atstring · date-time · nullableOptional

When the trigger was last updated

post/v1/{workspace_id}/triggers/{trigger_id}/resume
POST /v1/{workspace_id}/triggers/{trigger_id}/resume HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "event_type": "text",
  "event_filter": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "action_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_template": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": "text",
  "timezone": "text",
  "next_fire_at": "2026-01-01T00:00:00.000Z",
  "is_active": true,
  "created_by": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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.

Manually fire a trigger now

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
trigger_idstring · uuidRequired
Body
Responses
200

Successful Response

application/json
fired_event_idstring · uuidRequired
trigger_idstring · uuidRequired
statusconst: firedOptionalDefault: fired
post/v1/{workspace_id}/triggers/{trigger_id}/fire
POST /v1/{workspace_id}/triggers/{trigger_id}/fire HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "fired_event_id": "123e4567-e89b-12d3-a456-426614174000",
  "trigger_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "fired"
}

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.

List trigger execution history

get

Execution history from the durable trigger run table.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
trigger_idstring · uuidRequired
Query parameters
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/triggers/{trigger_id}/runs
GET /v1/{workspace_id}/triggers/{trigger_id}/runs HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "trigger_id": "123e4567-e89b-12d3-a456-426614174000",
      "fired_event_id": "123e4567-e89b-12d3-a456-426614174000",
      "source": "cron",
      "input_override": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "status": "queued",
      "attempt_count": 1,
      "max_attempts": 1,
      "next_attempt_at": "2026-01-01T00:00:00.000Z",
      "claimed_by": "text",
      "claimed_at": "2026-01-01T00:00:00.000Z",
      "lease_expires_at": "2026-01-01T00:00:00.000Z",
      "result_text": "text",
      "error": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

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

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:

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:

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 for details.

PreviousTool TestingNextMCP Server

Last updated

Was this helpful?