Trigger endpoints

Triggers are rules that automatically kick off agent sessions or runs when a condition is met. There are two trigger types: quote-based (fires when a market condition is true) and time-based (fires on a schedule).

List triggers

GET /api/triggers
Authorization: Bearer <token>

Response

{
  "triggers": [
    {
      "id": "trg_001",
      "type": "quote-based",
      "label": "NVDA gap up",
      "state": "active",
      "condition": { "symbol": "NVDA", "op": "gap_up", "threshold": 0.03 },
      "prompt": "Research NVDA after a gap-up open.",
      "tenant_id": "tnt_abc",
      "created_at": "2025-01-15T12:00:00Z"
    }
  ]
}

List trigger firings

GET /api/trigger-firings
Authorization: Bearer <token>

Returns the history of when triggers have fired. Useful for debugging why a session was started.

Response

{
  "firings": [
    {
      "id": "fire_001",
      "trigger_id": "trg_001",
      "fired_at": "2025-01-16T13:30:00Z",
      "session_id": "sess_xyz",
      "context": { "NVDA_open": 485.20, "NVDA_prev_close": 470.10 }
    }
  ]
}

Create a trigger

POST /api/triggers
Authorization: Bearer <token>
Content-Type: application/json

Quote-based
Time-based

{
  "type": "quote-based",
  "label": "NVDA gap up",
  "condition": {
    "symbol": "NVDA",
    "op": "gap_up",
    "threshold": 0.03
  },
  "prompt": "Research NVDA after a gap-up open."
}

{
  "type": "time-based",
  "label": "Weekly semis review",
  "schedule": "0 18 * * FRI",
  "prompt": "Run the weekly semis momentum review."
}

Field	Type	Required	Description
`type`	enum	yes	`quote-based` or `time-based`.
`label`	string	yes	Human-readable label.
`condition`	object	quote-based	Market condition (see below).
`schedule`	string	time-based	Cron expression.
`prompt`	string	yes	The prompt to feed the agent when the trigger fires.

Quote-based conditions

Field	Description
`symbol`	Ticker to watch.
`op`	Operator: `gap_up`, `gap_down`, `pct_change`, `crosses_above`, `crosses_below`.
`threshold`	Numeric threshold for the operator.

Response

{
  "id": "trg_001",
  "type": "quote-based",
  "label": "NVDA gap up",
  "state": "draft",
  "created_at": "2025-01-15T12:00:00Z"
}

Requires the triggers:write scope. New triggers start in the draft state.

Change trigger state

POST /api/triggers/{id}/state
Authorization: Bearer <token>
Content-Type: application/json

{ "state": "active" }

Triggers move through a lifecycle:

draft → active → retired

| State | Meaning | |---|---|---| | draft | Created but not yet armed. Does not fire. | | active | Armed. The scheduler evaluates the condition. | | retired | Decommissioned. No longer fires. Kept for audit. |

Response

{ "id": "trg_001", "state": "active" }

Dry-run a trigger

POST /api/triggers/dry-run
Authorization: Bearer <token>
Content-Type: application/json

{ "trigger_id": "trg_001" }

Evaluates the trigger condition against the latest market data without firing it. Useful for testing a condition before arming it.

Response

{
  "trigger_id": "trg_001",
  "would_fire": true,
  "evaluated_at": "2025-01-16T13:30:00Z",
  "context": { "NVDA_open": 485.20, "NVDA_prev_close": 470.10 }
}

Scopes — the triggers:write capability
Session endpoints — triggers create sessions when they fire
Trace events — trigger firings are traced

​List triggers

​Response

​List trigger firings

​Response

​Create a trigger

​Quote-based conditions

​Response

​Change trigger state

​Response

​Dry-run a trigger

​Response

​Related

List triggers

Response

List trigger firings

Response

Create a trigger

Quote-based conditions

Response

Change trigger state

Response

Dry-run a trigger

Response

Related