Trigger

Field	Type	Behavior	Description
name	string	OUTPUT_ONLY	Resource name (triggers/{id})
display_name	string		Human-readable name for the trigger
description	string		Description of what this trigger does
agent	string	REQUIRED	The agent to create sessions for. Format: agents/{agent}
configuration	TriggerConfiguration		Determines trigger type and behavior
enabled	boolean		Whether the trigger is enabled. Disabled cron triggers are not executed. Manual triggers can always be invoked regardless of this setting.
activation_state	TriggerActivationState	OUTPUT_ONLY	Runtime activation state. Currently only set for post_deploy triggers.
create_time	timestamp	OUTPUT_ONLY	When the trigger was created
update_time	timestamp	OUTPUT_ONLY	When the trigger was last modified
delete_time	timestamp	OUTPUT_ONLY	When the trigger was soft-deleted (null if active)

Example

{
  "name": "triggers/daily-health-check",
  "displayName": "Daily Health Check",
  "description": "Runs a health check every morning at 9 AM Eastern",
  "agent": "agents/health-checker",
  "configuration": {
    "cron": {
      "schedule": "0 9 * * *",
      "timezone": "America/New_York"
    }
  },
  "enabled": true,
  "createTime": "2026-02-06T01:42:31.481530Z",
  "updateTime": "2026-02-06T01:42:31.481530Z"
}

Trigger Configuration

Exactly one of the following fields must be set to determine the trigger type.

Field	Type	Description
cron	CronTriggerConfig	Trigger fires on the cron schedule
manual	ManualTriggerConfig	Trigger can only be manually invoked via InvokeTrigger
post_deploy	PostDeployTriggerConfig	Trigger fires once after a specific commit deploys

Cron Trigger Config

Field	Type	Required	Description
schedule	string	Yes	Standard 5-field cron expression (e.g. "0 9 * * *" for daily at 9 AM, "*/15 * * * *" for every 15 minutes)
timezone	string	No	IANA timezone for interpreting the schedule (e.g. "America/New_York"). Defaults to "UTC".

Manual Trigger Config

Empty object. Manual triggers have no automatic execution and can only be invoked via InvokeTrigger.

Post Deploy Trigger Config

Field	Type	Required	Description
repository	string	Yes	GitHub repository in "owner/repo" format
environment	string	Yes	Environment label to watch (e.g. "production", "staging")
sha	string	Yes	Commit SHA that must deploy before this trigger fires. Also fires for descendant commits. Immutable after creation.
delay	duration	Yes	How long to wait after the deployment before firing (e.g. "300s" for 5 minutes)

Trigger Activation State

Output-only state set by the system when a matching deployment is detected. Only post_deploy triggers have this set.

Field	Type	Description
post_deploy	PostDeployActivationState	Activation state for post-deploy triggers

Post Deploy Activation State

Field	Type	Description
deployment	string	The deployment that triggered activation (deployments/{id})
deployed_sha	string	The SHA that was actually deployed (may be a descendant of the configured SHA)
deploy_time	timestamp	Time of the deployment
fire_at_time	timestamp	Precomputed time to fire (deploy_time + delay)
fired_time	timestamp	When a session was created, or null if activated but not yet fired