---
title: "Save trigger definition"
method: POST
path: "/api/agents/{agentId}/trigger/save"
tags: ["Agent Triggers"]
---

# Save trigger definition

`POST /api/agents/{agentId}/trigger/save`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/agents/{agentId}/trigger/save`
- Auth: HTTP bearer

Create and save a new trigger definition for Jira, Jira Automation, Slack, Linear, Cron, generic Webhook, HackerOne, Bugcrowd, Zscaler, Darktrace, or SEON sources.

## Path parameters

- `agentId` string, uuid, required: Unique identifier of the agent

## Request body

- union: Request body for creating a new trigger, with different fields required based on the source type
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: Secret for webhook authentication
    - `webhookUrl` string, required: Webhook URL for Jira to call
    - `source` 'jira', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: Authentication token for Jira Automation
    - `webhookUrl` string, required: Webhook URL for Jira Automation to call
    - `source` 'jira-automation', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `source` 'slack', required
    - `allowedUserIds` string[]: Optional array of Slack user IDs allowed to trigger this agent
    - `allowedUsergroupIds` string[]: Optional array of Slack usergroup IDs allowed to trigger this agent
    - `allowedChannelIds` string[]: Optional array of Slack channel IDs where this trigger is allowed
    - `replyScope` 'anyone' | 'cotool_users': Who may reply in a Slack thread to continue this agent (anyone | cotool_users). Ignored when a user/usergroup allow list is set
    - `reactionEmojis` string[]: Slack emoji short names (no colons) that trigger this agent when added as a reaction to a message, e.g. ["rotating_light"]. Empty or absent means reactions do not trigger this agent
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid: Unique identifier for the trigger (required for legacy-webhook mode)
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string: Secret for webhook authentication (required for legacy-webhook mode)
    - `webhookUrl` string: Webhook URL for Linear to call (required for legacy-webhook mode)
    - `source` 'linear', required
    - `linearMode` 'agent-session' | 'legacy-webhook': Agent Session mode (default) or legacy webhook mode
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `source` 'cron', required
    - `schedule` string, required: Cron schedule expression (e.g., "0 9 * * 1-5" for weekdays at 9 AM)
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: Authentication token for the webhook
    - `webhookUrl` string, required: Webhook URL for external services to call
    - `source` 'webhook', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `emailAddress` string, required: Email address for the trigger
    - `source` 'email', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: HackerOne signing secret used to verify the X-H1-Signature header
    - `webhookUrl` string, required: Webhook URL for HackerOne to call
    - `source` 'hackerone', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: Bugcrowd-generated signing secret used to verify the X-Bugcrowd-Digest signature
    - `webhookUrl` string, required: Webhook URL for Bugcrowd to call
    - `source` 'bugcrowd', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: Token Zscaler sends in the X-Cotool-Webhook-Token header (or as a bearer token)
    - `webhookUrl` string, required: Webhook URL for Zscaler Cloud NSS feeds or alert webhooks to call
    - `source` 'zscaler', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: Generated HTTP Basic authentication password for Darktrace
    - `webhookUrl` string, required: Webhook URL for Darktrace to call
    - `source` 'darktrace', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode
  - object
    - `triggerId` string, uuid, required: Unique identifier for the trigger
    - `name` string, required: Display name for the trigger
    - `description` string: Optional description of what this trigger does
    - `secret` string, required: SEON-generated signing key used to verify the SEON-Signature header
    - `webhookUrl` string, required: Webhook URL for SEON to call
    - `source` 'seon', required
    - `eventMode` 'direct' | 'alert_source': Run the agent directly or create an alert before running it
    - `createAlert` boolean: Deprecated compatibility alias for eventMode

## Response `200`

Successful response

- object
  - `success` boolean, required
  - `data` object, required
    - `id` string, uuid, required
    - `agentId` string, uuid, required
    - `organizationId` string, uuid, required
    - `source` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required
    - `eventMode` 'direct' | 'alert_source': First-class event behavior. Missing only on legacy serialized snapshots.
    - `name` string, required
    - `description` string, nullable
    - `enabled` boolean, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `secret` string, nullable
    - `cronSchedule` string, nullable
    - `emailAddress` string, nullable
    - `config` object, required
    - `lastRunAttemptedAt` string, nullable
    - `lastRunSucceededAt` string, nullable
    - `alertCreatedNotificationDestinationIds` string[]: Slack destinations notified when this trigger creates an alert. Status updates and escalations for the alert reply in the thread that notification starts.

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)