> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doomberg.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger endpoints

> Create, manage, and dry-run quote-based and time-based triggers that drive automated agent sessions.

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

```http theme={null}
GET /api/triggers
Authorization: Bearer <token>
```

### Response

```json theme={null}
{
  "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

```http theme={null}
GET /api/trigger-firings
Authorization: Bearer <token>
```

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

### Response

```json theme={null}
{
  "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

```http theme={null}
POST /api/triggers
Authorization: Bearer <token>
Content-Type: application/json
```

<Tabs>
  <Tab title="Quote-based">
    ```json theme={null}
    {
      "type": "quote-based",
      "label": "NVDA gap up",
      "condition": {
        "symbol": "NVDA",
        "op": "gap_up",
        "threshold": 0.03
      },
      "prompt": "Research NVDA after a gap-up open."
    }
    ```
  </Tab>

  <Tab title="Time-based">
    ```json theme={null}
    {
      "type": "time-based",
      "label": "Weekly semis review",
      "schedule": "0 18 * * FRI",
      "prompt": "Run the weekly semis momentum review."
    }
    ```
  </Tab>
</Tabs>

| 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

```json theme={null}
{
  "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

```http theme={null}
POST /api/triggers/{id}/state
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{ "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

```json theme={null}
{ "id": "trg_001", "state": "active" }
```

## Dry-run a trigger

```http theme={null}
POST /api/triggers/dry-run
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{ "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

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

## Related

* [Scopes](/api/overview) — the `triggers:write` capability
* [Session endpoints](/api/sessions) — triggers create sessions when they fire
* [Trace events](/api/runs) — trigger firings are traced