---
title: "Create a trigger"
method: POST
path: "/triggers"
tags: ["Triggers"]
---

# Create a trigger

`POST /triggers`

Creates a trigger that runs a task on a schedule across a set of credentials. The trigger is created active and fires on its schedule immediately.

## Request body

- CreateTriggerRequest — Creates a trigger. The trigger is created with `status: "active"` and fires on its schedule immediately.
  - `name` string, required — Display name for the trigger.
  - `description` string, nullable — Description of the trigger's purpose.
  - `condition` TriggerCondition, required — When the trigger fires: a cron expression evaluated in a timezone.
    - `type` string, required — The condition type. Always `schedule`.
    - `cron` string, required — Standard 5-field cron expression: minute, hour, day of month, month, day of week.
    - `timezone` string, required — IANA timezone name the schedule is evaluated in (e.g. `America/New_York`). Day boundaries and DST shifts follow local time.
  - `task_id` string, required — The task to run. Prefixed with `task_`. Cannot be changed after creation.
  - `credential_ids` string[], nullable — Explicit credentials to target, one or many. Pass exactly one of `credential_ids` / `credential_filter`.
  - `credential_filter` TriggerCredentialFilter — A scope of credentials, resolved each time the trigger fires.
    - `source_ids` string[], required — Match credentials on any of these sources. IDs prefixed with `src_`. Pass `["*"]` to match every source in the organization; the wildcard must be the only entry.
    - `status` string[], required — Allowlist of credential statuses to fan out to, typically `unverified` and `verified`. There is no default, and an empty list is rejected. `invalid` / `deleted` credentials never match.
  - `input` unknown
  - `skip_if` TriggerSkipIf — Skip condition evaluated per credential before a run is created. When met, the credential is skipped for that fire and no run is created.
    - `last_run` TriggerSkipLastRun, required — Skips a credential when its most recent completed run of the trigger's task finished with `result` within `within_seconds`.
      - `result` string, required — Task run result to match: `success`, `failure`, or `unknown`.
      - `within_seconds` union, required — Time window in seconds, measured back from the fire time.
        - integer
        - string, int64
  - `concurrency_max` union — Maximum simultaneous runs from this trigger. Omit for no per-trigger cap.
    - integer
    - string, int32

## Response `201`

Created

- TriggerResponse — A trigger object. Triggers create task runs on a schedule across a set of credentials.
  - `id` string, required — Unique identifier for the trigger, prefixed with `trg_`.
  - `object` string, required — Always `trigger`.
  - `name` string, required — Display name for the trigger.
  - `description` string, nullable, required — Description of the trigger's purpose.
  - `status` string, required — `active` or `inactive`. Inactive triggers keep their configuration and fire nothing.
  - `condition` TriggerCondition, required — When the trigger fires: a cron expression evaluated in a timezone.
    - `type` string, required — The condition type. Always `schedule`.
    - `cron` string, required — Standard 5-field cron expression: minute, hour, day of month, month, day of week.
    - `timezone` string, required — IANA timezone name the schedule is evaluated in (e.g. `America/New_York`). Day boundaries and DST shifts follow local time.
  - `task_id` string, required — The task this trigger runs. Prefixed with `task_`. Fixed at creation.
  - `credential_ids` string[], nullable, required — Explicit credentials the trigger targets. `null` when the trigger uses `credential_filter`.
  - `credential_filter` TriggerCredentialFilter, required — A scope of credentials, resolved each time the trigger fires.
    - `source_ids` string[], required — Match credentials on any of these sources. IDs prefixed with `src_`. Pass `["*"]` to match every source in the organization; the wildcard must be the only entry.
    - `status` string[], required — Allowlist of credential statuses to fan out to, typically `unverified` and `verified`. There is no default, and an empty list is rejected. `invalid` / `deleted` credentials never match.
  - `input` unknown, required
  - `skip_if` TriggerSkipIf, required — Skip condition evaluated per credential before a run is created. When met, the credential is skipped for that fire and no run is created.
    - `last_run` TriggerSkipLastRun, required — Skips a credential when its most recent completed run of the trigger's task finished with `result` within `within_seconds`.
      - `result` string, required — Task run result to match: `success`, `failure`, or `unknown`.
      - `within_seconds` union, required — Time window in seconds, measured back from the fire time.
        - integer
        - string, int64
  - `concurrency_max` union, required — Maximum simultaneous runs from this trigger. `null` means no per-trigger cap.
    - integer
    - string, int32
  - `created_at` string, date-time, required — ISO 8601 timestamp of when the resource was created.
  - `updated_at` string, date-time, required — ISO 8601 timestamp of when the resource was last updated.
  - `request_id` string, required — Unique identifier for the API request. Include this when contacting support.

## Other responses

- `400` — Bad request — validation error or malformed input.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Not found — the requested resource does not exist.
- `409` — Conflict — the request is valid but cannot be completed in the current state.
- `422` — Unprocessable content — the request body is understood but contains invalid values.
- `429` — Too many requests or session concurrency exceeded. Retry with backoff; honor Retry-After and RateLimit headers when present.
- `500` — Internal server error.

---

[API](https://skmtc.dev/deck/apis/deck-api.md) · [All operations](https://skmtc.dev/deck/apis/deck-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/deck/deck-api/revisions/eba6e2cc9351/schema)