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.
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
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.
UTCSuccessful Response
Trigger display name
Human-readable description
Event type pattern to match
Action (skill) to invoke when fired
Cron schedule expression (e.g. '0 9 * * 1-5')
IANA timezone for schedule evaluation
Next scheduled fire time
Whether the trigger is active
Entity ID of the creator
When the trigger was created
When the trigger was last updated
Validation error
Rate limited
POST /v1/{workspace_id}/triggers HTTP/1.1
Host: platform.api-us.concurrence.com
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
50Successful Response
Validation Error
Rate limited
GET /v1/{workspace_id}/triggers HTTP/1.1
Host: platform.api-us.concurrence.com
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
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Trigger display name
Human-readable description
Event type pattern to match
Action (skill) to invoke when fired
Cron schedule expression (e.g. '0 9 * * 1-5')
IANA timezone for schedule evaluation
Next scheduled fire time
Whether the trigger is active
Entity ID of the creator
When the trigger was created
When the trigger was last updated
Trigger not found
Validation Error
Rate limited
GET /v1/{workspace_id}/triggers/{trigger_id} HTTP/1.1
Host: platform.api-us.concurrence.com
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
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.
Successful Response
Trigger display name
Human-readable description
Event type pattern to match
Action (skill) to invoke when fired
Cron schedule expression (e.g. '0 9 * * 1-5')
IANA timezone for schedule evaluation
Next scheduled fire time
Whether the trigger is active
Entity ID of the creator
When the trigger was created
When the trigger was last updated
Trigger not found
Validation error
Rate limited
PUT /v1/{workspace_id}/triggers/{trigger_id} HTTP/1.1
Host: platform.api-us.concurrence.com
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
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
No content
Validation Error
Rate limited
DELETE /v1/{workspace_id}/triggers/{trigger_id} HTTP/1.1
Host: platform.api-us.concurrence.com
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Trigger display name
Human-readable description
Event type pattern to match
Action (skill) to invoke when fired
Cron schedule expression (e.g. '0 9 * * 1-5')
IANA timezone for schedule evaluation
Next scheduled fire time
Whether the trigger is active
Entity ID of the creator
When the trigger was created
When the trigger was last updated
Trigger not found
Validation error
Rate limited
POST /v1/{workspace_id}/triggers/{trigger_id}/pause HTTP/1.1
Host: platform.api-us.concurrence.com
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Trigger display name
Human-readable description
Event type pattern to match
Action (skill) to invoke when fired
Cron schedule expression (e.g. '0 9 * * 1-5')
IANA timezone for schedule evaluation
Next scheduled fire time
Whether the trigger is active
Entity ID of the creator
When the trigger was created
When the trigger was last updated
Trigger not found
Validation error
Rate limited
POST /v1/{workspace_id}/triggers/{trigger_id}/resume HTTP/1.1
Host: platform.api-us.concurrence.com
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
firedTrigger not found
Validation error
Rate limited
Trigger scheduler not initialized
POST /v1/{workspace_id}/triggers/{trigger_id}/fire HTTP/1.1
Host: platform.api-us.concurrence.com
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.
Execution history from the durable trigger run table.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
50Successful Response
Validation Error
Rate limited
GET /v1/{workspace_id}/triggers/{trigger_id}/runs HTTP/1.1
Host: platform.api-us.concurrence.com
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.scheduledtask 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_idgives 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:
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:
trigger.fired- The trigger was activatedoutbound.scheduled- The outbound task was created with all scheduling parameterstrigger.completed- The action finished (includesduration_ms,events_written)outbound.dispatched- The call was placed (includescall_sid)outbound.completedoroutbound.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.
Last updated
Was this helpful?