# Trigger

URL: /business/nouns/trigger · Id: `noun:trigger`

> A Trigger is what starts a Workflow: an Event, a schedule, or a Thing entering a state.

A Trigger is what starts a [Workflow](/business/nouns/workflow): an [Event](/business/nouns/event), a schedule, or a [Thing](/business/nouns/thing) entering a state.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `event` | `string` | No | The Event selector it matches, such as `Order.placed`. |
| `schedule` | `string` | No | A cadence or cron expression. |
| `state` | `string` | No | The state whose entry fires it. |
| `where` | `string` | No | The predicate an `event` Trigger matches, such as `choice = 'raise'`. |
| `threshold` | `json` | No | A Metric staying below or above a value, optionally for a while, such as four weeks. |
| `at` | `string` | No | When in its cadence a schedule runs, on the namespace’s clock, such as `mon 09:00`. |

## Object
```json
{
  "$id": "https://api.sb/tutorloop.com/triggers/trigger_1",
  "$type": "Trigger",
  "event": "Example event",
  "schedule": "Example schedule",
  "state": "Example state",
  "where": "Example where",
  "threshold": {},
  "at": "Example at"
}
```

## Relationships
- <a id="rel-fires-on"></a>A Trigger **fires on** many [Events](/business/nouns/event): a Trigger fires each time an [Event](/business/nouns/event) matching its selector happens. `firesOn`, inverse [`fires`](/business/nouns/event#rel-fires).
- <a id="rel-starts"></a>A Trigger **starts** many [Workflows](/business/nouns/workflow): when a Trigger fires, each [Workflow](/business/nouns/workflow) it starts runs as a new [Action](/business/nouns/action). `starts`, inverse [`startedBy`](/business/nouns/workflow#rel-started-by).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Trigger.create](/business/nouns/trigger/create) | Creates a Trigger. Inherited from [Noun](/business/nouns/noun). | None. | `Trigger.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Trigger.get](/business/nouns/trigger/get) | Returns one Trigger by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Trigger.list](/business/nouns/trigger/list) | Returns Triggers, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Trigger.update](/business/nouns/trigger/update) | Changes the given properties of a Trigger. Inherited from [Noun](/business/nouns/noun). | None. | `Trigger.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Trigger.delete](/business/nouns/trigger/delete) | Deletes a Trigger; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Trigger.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Trigger.create` | Yes | Yes | Yes | No |
| `Trigger.get` | Yes | Yes | Yes | Yes |
| `Trigger.list` | Yes | Yes | Yes | Yes |
| `Trigger.update` | Yes | Yes | Yes | No |
| `Trigger.delete` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a trigger to QuietCopy.
```

**API**

```bash
curl -X POST https://api.sb/quietcopy.com/triggers \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"Example event"}'
```

```json
{
  "api": "https://api.sb/quietcopy.com",
  "trigger": {
    "$id": "https://api.sb/quietcopy.com/triggers/trigger_1",
    "$type": "Trigger",
    "event": "Example event",
    "schedule": "Example schedule"
  },
  "action": {
    "$id": "https://api.sb/quietcopy.com/actions/action_1",
    "operation": "Trigger.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/quietcopy.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const trigger = await $.Trigger.create({ event: 'Example event' })
```

**CLI**

```bash
npx startup-builder do Trigger.create --json '{"event":"Example event"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Trigger.create({ event: 'Example event' })"
  }
}
```

## Example
The Event `Lead.created` is the Trigger of [Answer inbound](/workflows/processes/inbound-sales/answer-inbound). The schedule `0 9 * * 1` is the Trigger of the [Monday Role review](/workflows/processes/role-review/monday-role-review).