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

Triggers

Schedule recurring automated actions with cron-based triggers that dispatch workspace actions on a defined cadence.

Triggers bind cron schedules to actions. When a trigger fires, the referenced action is dispatched and executed immediately. Each trigger is workspace-scoped and tracks its own execution history.

Use case: schedule a nightly patient outreach action, a weekly report generation, or periodic data quality checks. Any action that should run on a recurring basis without manual intervention.

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

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
is_activeboolean · nullableOptional
limitinteger · max: 100OptionalDefault: 10
continuation_tokenintegerOptionalDefault: 0
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokeninteger · nullableOptional
totalinteger · nullableOptional
get/v1/{workspace_id}/triggers

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}

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}

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}
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

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

Fire Trigger (Manual)

Manually dispatches the trigger's action immediately, regardless of the cron schedule or active state. Useful for testing trigger configurations before enabling the schedule.

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

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: 100OptionalDefault: 10
continuation_tokenintegerOptionalDefault: 0
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokeninteger · nullableOptional
totalinteger · nullableOptional
get/v1/{workspace_id}/triggers/{trigger_id}/runs

Event Types and Schedules

Every trigger declares an event_type, a workspace-defined identifier that names the kind of event the trigger emits when it fires. The event type appears on the world model events the fire produces, so it is how you distinguish one trigger's activity from another's in event queries; each execution history entry links to its originating event via fired_event_id. The optional event_filter narrows which events of that type the trigger responds to.

The schedule field is optional. Set a cron expression (evaluated in the trigger's timezone) for recurring triggers. Omit it for triggers that are fired only on demand - by an operator or by an external system calling the Fire Trigger endpoint.

Trigger Object

Field
Type
Description

id

string (UUID)

Trigger ID

workspace_id

string (UUID)

Owning workspace

name

string

Trigger name

description

string or null

Description

event_type

string

Event type identifier

event_filter

object or null

Filter conditions

action_id

string (UUID)

Action to dispatch

input_template

object

Input passed to the action

schedule

string or null

Cron expression

timezone

string

IANA timezone (default UTC)

next_fire_at

string (datetime) or null

Next scheduled fire time

is_active

boolean

Whether the trigger is active

created_by

string or null

API key entity that created the trigger

created_at

string (datetime)

Creation timestamp

updated_at

string (datetime)

Last update timestamp

External Activation

Triggers can be fired by external systems (CRMs, scheduling platforms, workflow automation tools) through direct, API-key-authenticated calls to the Fire Trigger endpoint. The external system POSTs to POST /v1/{workspace_id}/triggers/{trigger_id}/fire with an optional input override body, and the platform dispatches the trigger's action immediately.

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. Create a skill with action_type: "schedule_outbound_call"

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 immediately with a fired_event_id - the call itself is placed asynchronously:

  • The outbound call is scheduled and placed within the configured business-hours window (see the window field below). Expect a few minutes between the fire request and call placement.

  • Duplicate dispatch is prevented: a scheduled call is placed once even if the surrounding systems retry.

  • The agent loads patient context automatically when a patient_entity_id is linked.

  • If a call attempt fails and attempts remain, the call is retried with backoff (see retry_backoff_minutes and max_attempts). When attempts are exhausted, the task is marked failed.

  • The call outcome is recorded as a world model event either way.

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

Every trigger fire creates a chain of events you can 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 these events through world model event queries or the analytics layer. The trigger's execution history endpoint returns the durable run records, each linked to its originating event via fired_event_id.

Provenance

Events produced by trigger executions carry an AUTOMATION source tag, distinguishing them from conversation-driven or manual events in the world model. Each fire creates an event linked to the trigger entity, and each execution history run record links back to that event via fired_event_id.

CLI

Triggers can be managed through Agent Forge: forge platform trigger create|list|get|update|delete|pause|resume|fire|runs. See the Agent Forge reference for details.

PreviousTool TestingNextMCP Server

Last updated

Was this helpful?