# Triggers

A trigger is a request the workflow accepts, with the schema it must match. A run starts when a caller sends one, and every turn records which request opened it.

Trigger: API call → Run: New turn → Steps: Your steps → Wait: Question → Done: Finished

## Declaring what a workflow accepts

`Triggers` lists the requests the workflow accepts, each under `New` with a JSON Schema. `Prompt` and `Files` are the standard fields; a schema may require them and add its own. A workflow with one entry needs no name for it. With several, each is named and the caller says which one it is using with `?name=`.

```yaml
Triggers:
  - New: Refund
    Schema:
      type: object
      required: [Prompt, Invoice]
      properties:
        Prompt: { type: string }
        Invoice: { type: string }
        Instructions: { type: string }
```

The request becomes the turn’s first message to the model, one line per field, with the caller’s time zone and any files attached. A schema that declares an `Instructions` field lets the caller add to the workflow’s instructions for that turn.

## What starts a run

| Starter | Starts a run when | Input |
| --- | --- | --- |
| [API call](/docs/workflows/api/start-a-run/) | Your system calls POST /workflow/workflows/{workflowId}/runs with an API key from the Workflow organization’s Settings › API keys, or a signed-in person does. | The JSON you send |
| Another request | A later request arrives at POST /workflow/runs/{runId}/trigger. It opens the run’s next turn, with the earlier turns as its history. | The JSON you send |
| [Another workflow](/docs/workflows/steps/run-a-workflow/) | A WorkflowCall step runs it inside the caller’s turn. It opens no run of its own. | The step’s Input mapping |
| Momor Search | Someone asks a question in Search. Search runs the Answer workflow. | The question and where it was asked |

> **Schedules, email and webhooks**
> Workflows have no schedule, email or webhook starter yet. Start runs from your own scheduler or webhook handler with an API call.

## While a turn is still running

A run has at most one live turn. `Mode` decides what a new request does while the last turn is running, waiting for an answer, or failed and due for an automatic retry. It is `Queue` where the workflow declares none.

| Mode | What the new request does |
| --- | --- |
| `Queue` | Waits in the run’s queue and opens its turn when the live one ends. |
| `Reject` | Is refused with 409. No turn opens for it. |
| `Supersede` | Ends the live turn as Superseded and opens its own turn at once. |
| `QueueThenSupersedeAfter` | Queues; once it has waited WaitTimeout, ends the live turn as Superseded and opens. |
| `QueueThenRejectAfter` | Queues; if it has not opened within WaitTimeout, it is retired without running. |

```yaml
Mode: QueueThenSupersedeAfter
WaitTimeout: PT30S
```

`WaitTimeout` is a duration, as ISO 8601 (`PT30S`) or a TimeSpan (`00:00:30`). The two modes ending in `After` require it and the other three refuse it. Queued requests open in the order they arrived.