---
title: "Create Trigger"
method: POST
path: "/v1/triggers/"
tags: ["v1", "protected", "triggers"]
---

# Create Trigger

`POST /v1/triggers/`

Create a new trigger.

Creates a new trigger with the specified configuration. The trigger will be
validated and, if it's a cron trigger, automatically scheduled.

If channel_credentials are provided, they are stored encrypted in the secret
store under key ``channel_cred:{webhook_type}:{trigger_id}``.

Args:
    payload: Trigger creation DTO (single source of truth shared with MCP toolset).
    user_context: Authentication context.
    trigger_service: Injected trigger service.
    secret_manager: Injected secret manager for credential storage.

Returns:
    The created trigger.

Raises:
    HTTPException: If validation fails or creation errors occur.

## Request body

- TriggerCreate — Payload for creating a trigger. A trigger fires an agent — either on a cron schedule (``trigger_type='cron'``) or in response to an inbound webhook (``trigger_type='webhook'``). For poll-based channels (e.g. email inbox), use ``trigger_type='polling'`` plus a ``data_extractor`` configuration.
  - `agent_id` string, uuid, required — UUID of the agent to invoke when the trigger fires.
  - `allowed_methods` string[] — HTTP methods accepted on the webhook endpoint.
  - `channel_credentials` object, nullable — Channel credentials (bot_token, SMTP password, etc). Stored encrypted in the secret store. Never returned in responses.
  - `conditions` object — Optional conditions evaluated against event data before firing.
  - `cron_expression` string, nullable — 5- or 6-field cron expression (required when trigger_type='cron').
  - `data_extractor` string, nullable — Polling extractor identifier (e.g. 'imap', 'rss').
  - `data_extractor_config` object, nullable — Connection/auth details for the polling extractor.
  - `description` string — Short summary of what this trigger does.
  - `enabled` boolean — Whether the trigger is active immediately on creation.
  - `event_types` string[] — Event types to filter on (empty list = accept all events).
  - `failure_threshold` integer — Auto-disable after this many consecutive failed executions.
  - `name` string, required — Human-readable trigger name.
  - `task_parameters` object — Parameters merged into the task created when the trigger fires.
  - `timezone` string — IANA timezone for cron evaluation (e.g. 'UTC', 'America/New_York').
  - `trigger_type` 'cron' | 'webhook' | 'polling', required — 'cron' for scheduled, 'webhook' for inbound HTTP, 'polling' for extractor-driven.
  - `validation_rules` object — Per-channel validation rules (signature secrets, allowed senders, etc).
  - `webhook_config` object, nullable — Channel-specific configuration (bot tokens, signing keys, etc).
  - `webhook_id` string, nullable — Public webhook path segment. Auto-generated if omitted for webhook triggers.
  - `webhook_type` string — Channel type: 'generic', 'telegram', 'slack', 'discord', etc.

## Response `201`

Successful Response

- TriggerResponse — Response model for trigger data.
  - `agent_id` string, uuid, required
  - `allowed_methods` string[], nullable
  - `conditions` object, required
  - `consecutive_failures` integer, required
  - `created_at` string, required
  - `created_by` string, required
  - `cron_expression` string, nullable
  - `data_extractor` string, nullable
  - `description` string, required
  - `event_types` string[]
  - `failure_threshold` integer, required
  - `has_channel_credentials` boolean
  - `id` string, uuid, required
  - `is_active` boolean, required
  - `last_execution_at` string, nullable
  - `name` string, required
  - `next_run_time` string, nullable
  - `task_parameters` object, required
  - `timezone` string, nullable
  - `trigger_type` string, required
  - `updated_at` string, required
  - `validation_rules` object, nullable
  - `webhook_config` object, nullable
  - `webhook_id` string, nullable
  - `webhook_type` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentarea/apis/agentarea-api.md) · [All operations](https://skmtc.net/agentarea/apis/agentarea-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentarea/agentarea-api/revisions/082e677c141c/schema)