AGagentarea
v1
protected
triggers

Create Trigger

Changed on

Create a cron trigger (scheduled at once) or a stream trigger (subscribed to its stream).

A webhook or a polled provider is a source of a stream; its events fire a stream trigger on that stream.

post/v1/workspaces/{workspace}/triggers/

Request

Path parameters

workspacestring required

Slug of the workspace the request acts in

Request body

agent_idstring uuid required

UUID of the agent to invoke when the trigger fires.

conditionsobject

Optional conditions evaluated against event data before firing. An LLM condition ({"type": "llm", "description": ...}) must name the chat or decision model instance that evaluates it in "model_id"; each sub-condition of a combined condition names its own.

cron_expressionstring nullable

5- or 6-field cron expression (required when trigger_type='cron').

descriptionstring

Short summary of what this trigger does.

enabledboolean

Whether the trigger is active immediately on creation.

event_filterobject nullable

Which events of the stream fire it: {"kinds": ["push"], "fields": {"raw_data.action": "opened"}}. Empty means every event.

failure_thresholdinteger

Auto-disable after this many consecutive failed executions.

namestring required

Human-readable trigger name.

stream_idstring uuid nullable

Stream whose events fire this trigger (required when trigger_type='stream').

task_definition_idstring uuid nullable

Saved task the trigger runs, of the same agent: its text and parameters are what each firing asks, in place of task_parameters.

task_parametersobject

Parameters merged into the task created when the trigger fires.

timezonestring

IANA timezone for cron evaluation (e.g. 'UTC', 'America/New_York').

trigger_type'cron' | 'stream' required

'cron' for scheduled, 'stream' to run on the events of a stream (a webhook or a polled provider is a source of a stream).

Response

Successful Response

agent_idstring uuid required
conditionsobject required
consecutive_failuresinteger required
created_atstring date-time required
created_bystring required
cron_expressionstring nullable
descriptionstring required
event_filterobject nullable

Which events fire it.

failure_thresholdinteger required
idstring uuid required
is_activeboolean required
last_event_atstring date-time nullable

When the trigger's stream last recorded an event.

last_execution_atstring date-time nullable
namestring required
needs_new_owner_atstring date-time nullable
next_run_timestring date-time nullable
status'active' | 'inactive' | 'needs_owner' required

'needs_owner' when the person who configured it can no longer run its agent; the trigger stays stopped until it is enabled again, and the next event re-checks that person's access.

stream_idstring uuid nullable

Stream whose events fire this trigger.

task_definition_idstring uuid nullable

Saved task each firing asks, in place of task_parameters.

task_parametersobject required
timezonestring nullable
trigger_typestring required
updated_atstring date-time required

Changes

  • 1868622eed6dRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

  • 1d8a3995ec6cRevision changes
    • breaking

      removed the enum value polling of the request property

    • breaking

      removed the enum value webhook of the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status