Triggers

Triggers are automated event handlers. They fire on cron schedules, inbound webhooks, file changes, HTTP polling, incoming email, or at a specific datetime (once). Each trigger executes a shell command or an agent prompt when it fires.

GET/triggersAuthenticated

List all triggers, optionally filtered by type or enabled state.

Parameter	Type	Required	Description
`type`	`string`	No	Filter by type (query param)
`enabled`	`boolean`	No	Filter by enabled state (query param)

curl "http://127.0.0.1:7741/triggers?type=cron&enabled=true" \
  -H "Authorization: Bearer $TOKEN"

GET/triggers/:idAuthenticated

Get a single trigger by ID. Webhook triggers include the computed webhook_url.

POST/triggersAuthenticated

Create a new trigger.

Parameter	Type	Required	Description
`type`	`string`	Yes	Trigger type: cron, webhook, file, http, email, or once
`config`	`object`	Yes	Type-specific configuration (see below)
`action`	`object`	Yes	Action to execute: { type: "shell"\|"agent", command?, prompt?, notify? }
`label`	`string`	No	Human-readable display name
`enabled`	`boolean`	No	Start enabled (default: true)
`max_runs`	`number`	No	Auto-disable after N fires (0 = unlimited)

Config by Type

Type	Config Fields
`cron`	`expression` (cron string), `timezone?`
`webhook`	`service?` (stripe, github, paypal, twilio), `secret?` (HMAC key)
`file`	`paths` (string[]), `events?` (create, modify, delete), `debounceMs?`
`http`	`url`, `method?`, `headers?`, `intervalMs?`, `jqFilter?`
`email`	`connector?` (gmail, outlook), `user?`, `intervalMs?`
`once`	`at` (ISO 8601 datetime string)

curl -X POST http://127.0.0.1:7741/triggers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cron",
    "config": { "expression": "0 9 * * MON", "timezone": "America/New_York" },
    "action": { "type": "agent", "prompt": "Summarize my week" },
    "label": "Weekly summary"
  }'

201Response

{
  "ok": true,
  "data": {
    "id": "a1b2c3d4",
    "type": "cron",
    "enabled": true,
    "label": "Weekly summary",
    "run_count": 0,
    "created_at": "2026-03-03T12:00:00Z"
  }
}

PUT/triggers/:idAuthenticated

Update an existing trigger (partial update).

Parameter	Type	Required	Description
`config`	`object`	No	Updated type-specific config
`action`	`object`	No	Updated action
`label`	`string`	No	Updated label
`enabled`	`boolean`	No	Enable or disable
`max_runs`	`number`	No	Updated max runs

DELETE/triggers/:idAuthenticated

Delete a trigger permanently.

200Response

{
  "ok": true,
  "data": {
    "id": "a1b2c3d4",
    "status": "deleted"
  }
}

POST/triggers/:id/toggleAuthenticated

Toggle a trigger between enabled and disabled.

POST/triggers/:id/fireAuthenticated

Manually fire a trigger for testing.

Parameter	Type	Required	Description
`payload`	`any`	No	Optional test payload

Auto-Disable

Triggers auto-disable after 5 consecutive errors or when max_runs is reached. Disabled triggers can be re-enabled via the toggle endpoint.