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

# Triggers

> Automate agent execution with events, schedules, or API calls.

A trigger runs an agent automatically — either when an event occurs in an external service, on a recurring schedule, or on demand via an API request.

<iframe src="https://www.youtube.com/embed/DsUDLPRKNsY" title="YouTube video player" frameborder="0" className="w-full aspect-video rounded-xl" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Trigger types

<CardGroup cols={3}>
  <Card title="Event" icon="bolt" href="#event-triggers">
    Fires when an event occurs in a connected service, such as a new Slack mention or a GitHub pull request.
  </Card>

  <Card title="Scheduled" icon="calendar-days" href="#scheduled-triggers">
    Fires on a recurring schedule: hourly, daily, weekly, or monthly.
  </Card>

  <Card title="API" icon="code" href="#api-triggers">
    Fires on demand when an authenticated HTTP request is made to the workspace session endpoint.
  </Card>
</CardGroup>

## Create a trigger

<Steps>
  <Step title="Open your workspace">
    Go to [guild.ai](https://guild.ai) and open the workspace where the agent is installed.
  </Step>

  <Step title="Go to Triggers">
    In the left sidebar, open **More** and click **Triggers**, then click **New trigger**.
  </Step>

  <Step title="Choose a type">
    Select **Event**, **Scheduled**, or **API**, then configure the trigger.
  </Step>

  <Step title="Select an agent">
    Choose the agent the trigger will run when it fires.
  </Step>
</Steps>

## Event triggers

Event triggers fire when a specific event occurs in a connected service.

<Note>
  In the CLI and REST API, event triggers are referred to as `webhook` triggers.
</Note>

### Supported services

| Service      | Example events                                |
| ------------ | --------------------------------------------- |
| Slack        | `app_mention`, `message`                      |
| GitHub       | `pull_request`, `issues`, `push`              |
| Linear       | `issue`, `comment`                            |
| Jira         | `issue_created`, `issue_updated`              |
| Azure DevOps | `workitem.created`, `git.pullrequest.created` |
| Google Docs  | Document changes                              |
| Notion       | Page updates                                  |

Configure the service, event type, and optional event action when creating the trigger. By default, the agent receives the event payload as its input.

### Agent input

Webhook triggers support a customizable agent input, identical to the agent input on time triggers. Open the **Edit Trigger** dialog to edit it.

On desktop, a schema-driven panel appears on the right side of the dialog. On mobile, a text field appears instead. When no input has been saved, the field pre-populates with a default based on the integration name, event type, and action.

### Custom agent input for webhook triggers

By default, the agent receives the raw webhook payload as its input. You can override this by providing a custom `agent_input` object when creating the trigger. The custom input is merged with (or replaces) the default payload delivered to the agent.

Use custom agent input when you want to:

* Pass a fixed system prompt or configuration alongside the webhook payload
* Map specific webhook fields to a named input schema your agent expects

```bash theme={null}
guild trigger create \
  --type webhook \
  --service GITHUB \
  --event pull_request \
  --action opened \
  --agent code-reviewer \
  --agent-input '{"review_style": "concise", "post_comment": true}'
```

Custom `agent_input` can also be set from the web UI when creating or editing a webhook trigger.

### Pass the webhook payload unaltered

When you create or edit an event trigger in the web UI, select **Pass the webhook payload unaltered** to forward the raw webhook JSON payload directly to the agent. Checking this option disables and clears the input editor, so you do not need to define a custom input template to deliver the payload as-is.

This option corresponds to an empty `agent_input` in the CLI and REST API, which the backend treats as "forward the payload unaltered."

<Note>
  Toggling **Pass the webhook payload unaltered** is non-destructive. If you uncheck it, the input editor restores the agent input template you previously entered.
</Note>

### Scope events with `service_config`

Use `service_config` to restrict event triggers to specific repositories, channels, or projects. Webhook triggers accept an optional `service_config` JSON object. When you omit it or set it to `null`, the trigger matches **all** events of the selected type (for example, every repository or every channel).

| Service | Field         | Example                  | Behavior                                                                                                   |
| ------- | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| GitHub  | `repo`        | `"guildaidev/guildcode"` | Only events for this repository (`owner/repo` format)                                                      |
| Slack   | `channel_ids` | `["C01234567"]`          | Only events in these channel IDs. Messages from the Slack app itself are always excluded to prevent loops. |
| Jira    | `project`     | `"ENG"`                  | Only events for this project key (case-insensitive)                                                        |

`service_config` must be a JSON object. Do not pass an array or string at the top level.

Pass `service_config` when you create or update a trigger with the CLI:

```bash theme={null}
# GitHub: only pull requests in one repo
guild trigger create \
  --type webhook \
  --service GITHUB \
  --event pull_request \
  --action opened \
  --agent code-reviewer \
  --service-config '{"repo": "guildaidev/guildcode"}'

# Slack: only mentions in specific channels
guild trigger create \
  --type webhook \
  --service SLACK \
  --event app_mention \
  --agent slack-assistant \
  --service-config '{"channel_ids": ["C01234567"]}'
```

<Warning>
  For Slack, an empty `channel_ids` array matches **all** channels. Omit `service_config` entirely only if you intend to process events workspace-wide.
</Warning>

### Session affinity with `session_affinity_key`

By default, Guild uses integration-specific logic to determine which session an incoming webhook event belongs to. Set `session_affinity_key` to extract the session correlation ID directly from the webhook payload instead.

`session_affinity_key` is a dot-notation path into the webhook payload. The value at that path becomes the `remote_id` that matches the event to an existing session. When the extracted value matches a prior event's `remote_id`, the agent continues in that session rather than starting a new one. When set, `session_affinity_key` overrides the integration handler's default session correlation logic.

For example, `"event.thread_ts"` extracts the Slack thread timestamp from a payload structured as `{"event": {"thread_ts": "1234567890.123"}}`.

<Note>
  If the path does not resolve — because the field is absent or an intermediate value is not an object — the trigger falls back to no affinity and starts a new session.
</Note>

### CLI

```bash theme={null}
# Create a Slack event trigger
guild trigger create \
  --type webhook \
  --service SLACK \
  --event app_mention \
  --agent slack-assistant

# Create a GitHub event trigger for opened pull requests
guild trigger create \
  --type webhook \
  --service GITHUB \
  --event pull_request \
  --action opened \
  --agent code-reviewer
```

***

## Scheduled triggers

Scheduled triggers fire on a recurring schedule and run the agent with a fixed input.

<Note>
  In the CLI and REST API, scheduled triggers are referred to as `time` triggers.
</Note>

### Frequencies

| Frequency | Options                    |
| --------- | -------------------------- |
| `HOURLY`  | —                          |
| `DAILY`   | Time of day                |
| `WEEKLY`  | Days of week, time of day  |
| `MONTHLY` | Days of month, time of day |

### CLI

```bash theme={null}
# Daily trigger at 9:00 AM
guild trigger create \
  --type time \
  --frequency DAILY \
  --time 09:00 \
  --agent daily-report \
  --input '{"project": "GUILD"}'

# Weekly trigger on Monday mornings
guild trigger create \
  --type time \
  --frequency WEEKLY \
  --days-of-week monday \
  --time 09:00 \
  --agent weekly-summary
```

***

## API triggers

An API trigger runs the agent on demand via an authenticated HTTP request. API triggers require an API key to authenticate requests.

### Generate an API key

API keys are created and managed via the web UI:

1. Go to **Triggers** in your workspace and click **New trigger**.
2. Select **API** and choose the agent this trigger will run.
3. Once the trigger is created, copy the combined credentials string (`<api_key_id>:<api_key_secret>`) displayed in the dialog. The generated string contains **both** the api\_key\_id and api\_key\_secret.

<Note>
  Creating and managing API keys is currently exclusive to the web UI. There is no CLI subcommand available for managing API keys.
</Note>

### Authentication

Guildcode uses HTTP Basic Authentication to authorize API requests. Pass the combined credentials string as the authentication parameter (for example, with `curl -u`):

### Trigger a session

To start a new agent session, make a `POST` request to the workspace's sessions endpoint:

```http theme={null}
POST /api/workspaces/{owner_name}/{workspace_name}/sessions
```

#### Request body

The request body must be a JSON object with:

* `session_type`: Must be set to `"api_trigger"`.
* `agent_input`: A JSON object matching the input schema of your agent.

#### Example

```bash theme={null}
curl -X POST https://app.guild.ai/api/workspaces/<owner_name>/<workspace_name>/sessions \
  -u "<api_key_id>:<api_key_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_type": "api_trigger",
    "agent_input": {
      "text": "Hello, agent!"
    }
  }'
```

### Interactive follow-up

If the agent is conversational or awaits subsequent inputs, you can post follow-up events directly to the session:

```http theme={null}
POST /api/sessions/{session_id}/events
```

#### Request body

* `mode`: Set to `"text"` (default), `"json"`, or `"multimodal"`.
* `content`: The message content. For `"text"` mode, a string; for `"json"` mode, a JSON object; for `"multimodal"` mode, a non-empty array of content part objects.

When `mode` is `"multimodal"`, each content part is an object with a `type` field:

* When `type` is `"text"`, the object must include a non-empty `"text"` string.
* When `type` is `"image"` or `"file"`, the object must include a valid `"attachment_id"` that references an uploaded attachment.

A single message supports a maximum of 5 attachments.

#### Example

```bash theme={null}
curl -X POST https://app.guild.ai/api/sessions/<session_id>/events \
  -u "<api_key_id>:<api_key_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "text",
    "content": "Follow-up question or answer goes here"
  }'
```

#### Multimodal example

Send a message with both a text part and an image attachment:

```bash theme={null}
curl -X POST https://app.guild.ai/api/sessions/<session_id>/events \
  -u "<api_key_id>:<api_key_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "multimodal",
    "content": [
      { "type": "text", "text": "Here is the screenshot you asked about." },
      { "type": "image", "attachment_id": "<attachment_id>" }
    ]
  }'
```

### Retrieve session status

Retrieve the current execution state and metadata of a specific session:

```http theme={null}
GET /api/sessions/{session_id}
```

#### Example

```bash theme={null}
curl -X GET https://app.guild.ai/api/sessions/<session_id> \
  -u "<api_key_id>:<api_key_secret>"
```

### Fetch session events (logs and thoughts)

Retrieve the chronological feed of logs, agent thought progress, LLM usage statistics, tool calls, and final outputs:

```http theme={null}
GET /api/sessions/{session_id}/events
```

#### Query parameters (Optional)

* `limit`: Maximum number of events to return (default: 20).
* `types`: Filter by specific event types (e.g., `agent_console`).

#### Example

```bash theme={null}
curl -X GET "https://app.guild.ai/api/sessions/<session_id>/events?limit=100" \
  -u "<api_key_id>:<api_key_secret>"
```

### Fetch session sub-tasks

Fetch a list of all sub-tasks spawned by parent agents or tool calls inside this session:

```http theme={null}
GET /api/sessions/{session_id}/tasks
```

#### Example

```bash theme={null}
curl -X GET https://app.guild.ai/api/sessions/<session_id>/tasks \
  -u "<api_key_id>:<api_key_secret>"
```

### Real-time streaming (WebSockets)

If you are developing a real-time interface or monitoring tool, establish a WebSocket connection rather than polling. Pass your Basic Auth credentials in the connection headers.

* **Live Messages and Logs Feed:** `wss://app.guild.ai/api/sessions/<session_id>/events/ws`
* **Real-time LLM Token Streams:** `wss://app.guild.ai/api/sessions/<session_id>/response-stream-drafts/ws`
* **Sub-task Progress Feed:** `wss://app.guild.ai/api/sessions/<session_id>/tasks/ws`

### Security and scope

* **Workspace Scope:** The API key carries workspace-level permissions. This allows it to read and write (including fetching status, event feeds, sub-tasks, and runtime statuses, as well as sending follow-up events/messages) to **any session** in the same workspace.
* **Execution Identity:** Sessions started via an API key do not run on behalf of a human user (`acting_user_id` is `None`). However, when viewing the session's chat feed in the UI, any events generated by the API will display the avatar of the user who originally created the trigger.

***

## Manage triggers

### Activate and deactivate

Deactivate a trigger to pause it without deleting it.

```bash theme={null}
guild trigger deactivate <trigger-id>
guild trigger activate <trigger-id>
```

### List and inspect

```bash theme={null}
# List all triggers in the workspace
guild trigger list

# Get details for a specific trigger
guild trigger get <trigger-id>

# List sessions spawned by a trigger
guild trigger sessions <trigger-id>
```

### Update

```bash theme={null}
# Change the schedule of a scheduled trigger
guild trigger update <trigger-id> --time 10:00

# Change the event of an event trigger
guild trigger update <trigger-id> --event message
```