Skip to main content
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

{
  "type": "quote-based",
  "label": "NVDA gap up",
  "condition": {
    "symbol": "NVDA",
    "op": "gap_up",
    "threshold": 0.03
  },
  "prompt": "Research NVDA after a gap-up open."
}
FieldTypeRequiredDescription
typeenumyesquote-based or time-based.
labelstringyesHuman-readable label.
conditionobjectquote-basedMarket condition (see below).
schedulestringtime-basedCron expression.
promptstringyesThe prompt to feed the agent when the trigger fires.

​
Quote-based conditions

FieldDescription
symbolTicker to watch.
opOperator: gap_up, gap_down, pct_change, crosses_above, crosses_below.
thresholdNumeric 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 }
}