> Source: https://builder.ema.ai/v2/api-reference/triggers
> Title: Triggering AI Employees

# Triggering AI Employees

An AI Employee does nothing until something starts a run. This page is the map of every way a run can begin — from a button in the builder to a scheduled job to a document landing in a knowledge base — and the `trigger_type` each one stamps on the run so you can tell them apart in run history. Every trigger ultimately produces a workflow run; what differs is who or what kicks it off and how the inputs arrive.

Each trigger records its origin on the run. You can filter run history by it: `GET /api/v1/workflow/workflows/{id}/runs?trigger_type=schedule`. The recorded values are:

`trigger_type`

Started by

`ui`

A person running the AI Employee from the builder or run surface.

`api`

A direct call to the run endpoint with a JWT or API key.

`schedule`

A recurring schedule firing.

`webhook`

An inbound webhook (e.g. a ticketing-system callback).

`feedback`

A user submitting feedback that runs a feedback workflow.

`document`

A document arriving in a knowledge base that a document trigger watches.

All API examples require a [JWT or tenant API key](/builder/v2/api-reference/authentication) and use `https://your-tenant.ema.co` as the host.

## Run from the API

The most direct trigger is calling the run endpoint yourself. This is the right choice for one-off automation, batch jobs, and integrating an AI Employee into your own backend.

```http
POST https://your-tenant.ema.co/api/v1/workflow/workflows/{id}/run
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{ "input_params": { "subject": "Order #4821 hasn't shipped" } }
```

The response is `202 Accepted` with the run; the run is stamped `trigger_type=api`. Follow it with the SSE stream or poll run details — see the [Workflow API](/builder/v2/api-reference/workflow-api) for the run lifecycle, streaming, and inspection endpoints. For a conversation rather than a single run, use the [Chat API](/builder/v2/api-reference/chat-api).

## Run on a schedule

Attach a recurring schedule so the AI Employee runs on its own cadence. Scheduled runs are stamped `trigger_type=schedule`.

-   **Create or update:** `PUT /api/v1/workflow/workflows/{id}/schedule`.
-   **Enable:** `POST /api/v1/workflow/workflows/{id}/schedule/enable` — requires a published version, otherwise `409`.
-   **Disable:** `POST /api/v1/workflow/workflows/{id}/schedule/disable`.
-   **Delete:** `DELETE /api/v1/workflow/workflows/{id}/schedule`.

A scheduled run carries `scheduled_fire_time`; if the scheduler skips a fire (for example, because a prior run is still going under an overlap policy), the resulting run records a `skip_reason`.

## Run on a new document (document triggers)

A document trigger watches a knowledge base and starts a run whenever a matching document is added — useful for "process every contract that lands here" automations. Each watch is a **binding** between the workflow and a knowledge-base scope. Runs started this way are stamped `trigger_type=document`.

Manage bindings under the workflow:

-   **Create a binding:** `POST /api/v1/workflow/workflows/{id}/document-triggers`. Returns `409` if an overlapping binding already exists.
-   **List bindings:** `GET /api/v1/workflow/workflows/{id}/document-triggers`.
-   **Get / update / delete one:** `GET` / `PUT` / `DELETE /api/v1/workflow/workflows/{id}/document-triggers/{binding_id}`.
-   **Enable / disable:** `POST /api/v1/workflow/workflows/{id}/document-triggers/{binding_id}/enable` and `.../disable`.

```http
POST https://your-tenant.ema.co/api/v1/workflow/workflows/3f7a.../document-triggers
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "knowledge_base_id": "kb-9f2a...",
  "folder_prefix": "contracts/",
  "fire_on": "created",
  "enabled": true
}
```

Only `knowledge_base_id` is required. Narrow the watch with `folder_prefix` (match documents whose folder path starts with it) and `mime_type_allowlist`. `fire_on` defaults to `created`. A disabled binding stays configured but stops firing — toggle it without deleting and recreating.

## Run from a chat conversation

For a chat-modality AI Employee, each user message triggers a run behind the scenes. You don't call the run endpoint directly; you send a message to a session and the chat service starts the run for you:

```http
POST https://your-tenant.ema.co/api/v1/chat/sessions/{session_id}/messages
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{ "content": "What's the status of my refund?" }
```

The response includes the `run_id`; stream it to receive the reply. See the [Chat API](/builder/v2/api-reference/chat-api) for the full session-and-message flow.

## Run from an external system

Two server-to-server endpoints on the chat service let a trusted external system converse with an AI Employee on behalf of _its own_ end users. Both authenticate with a tenant API key and forward an end-user identity into the run's `user_context`, so the AI Employee can personalize its answer.

### External channel trigger

`POST /api/v1/chat/external/trigger` is for an external channel (web widget, Slack, Teams) where the end user is identified by a bearer token your system holds. The chat service resolves that token to a user, finds or creates a session, and sends the message with the resolved identity injected.

```http
POST https://your-tenant.ema.co/api/v1/chat/external/trigger
X-API-Key: ema_sk_live_2f9c...redacted
Content-Type: application/json

{
  "bearer_token": "the-end-users-token",
  "workflow_id": "3f7a...",
  "channel_type": "web",
  "message": "Where is my order?"
}
```

The response is `202 Accepted` with `message_id`, `assistant_message_id`, `run_id`, and `session_id`. Optionally pass `conversation_id` for continuity across turns and `user_context_override` to supply the workflow's `user_context` verbatim.

### Partner-API chat

`POST /api/v1/chat/external/chat` is for trusted partners that supply the end-user identity directly — Ema does not validate it. Authenticate with a tenant API key (`X-API-Key`); the key's tenant scopes the session.

```http
POST https://your-tenant.ema.co/api/v1/chat/external/chat
X-API-Key: ema_sk_live_2f9c...redacted
Content-Type: application/json

{
  "external_user_id": "partner-user-42",
  "workflow_id": "3f7a...",
  "message": "Reset my PIN",
  "user_context": { "email": "user@partner.com", "attributes": { "tier": "gold" } }
}
```

Identity resolves from `external_user_id` (recommended) or, if absent, `user_context.email`; with neither, the call returns `422`. Omit `conversation_id` for a single-shot exchange, or provide one to continue an existing conversation. The endpoint returns `202` immediately and materializes the assistant message asynchronously — poll the run status to retrieve it.

> [INFO]
> **Which external endpoint?** Use `/external/trigger` when you hold a token that _identifies_ the end user and want Ema to resolve it. Use `/external/chat` when you are a trusted partner asserting the identity yourself and forwarding a `user_context` directly.

## Run from the builder UI

Running an AI Employee from the builder or its run surface produces a run stamped `trigger_type=ui`. You don't call this trigger from the API — it's how interactive testing and manual runs in the product are recorded. It's listed here so the `ui` value in run history is unambiguous.

## What's next

-   [Workflow API](/builder/v2/api-reference/workflow-api) — the run lifecycle, streaming, run history, and HITL.
-   [Chat API](/builder/v2/api-reference/chat-api) — sessions and messages, which back the chat and external triggers.
-   [Authentication](/builder/v2/api-reference/authentication) — the JWT and tenant API key each trigger requires.