---
title: "Create Automation"
method: POST
path: "/v1/automations"
tags: ["Automation"]
---

# Create Automation

`POST /v1/automations`

Creates a new automation in your organization. The automation is bound to a single environment, which determines the repository (or repository set) and resolved env vars / MCPs / skills used when the automation fires.

## Request body

- CreateAutomationRequest — Request body for creating a new automation. The automation runs in a single environment specified by `environment_id`.
  - `name` string, required — Human-readable name for the automation
  - `description` string — Optional description
  - `scope` 'org' | 'user' — Automation scope. `org` (default) creates an org-owned automation visible to all members. `user` creates a personal automation scoped to the authenticated user.
  - `triggers` AutomationTrigger[], required — One or more triggers. Duplicates are not allowed: at most one cron trigger, and at most one event-based trigger per event (e.g. two triggers for `pull_request.opened` is rejected, but `pull_request.opened` + `merge_request.opened` is fine).
    - `type` 'cron' | 'github' | 'gitlab' | 'slack' | 'sentry' | 'custom', required — The trigger type
    - `config` union, required — Trigger-specific configuration. When `type` is `cron`, this is a `CronTriggerConfig`. When `type` is `github`, this is a `GitHubTriggerConfig`. When `type` is `gitlab`, this is a `GitLabTriggerConfig`. When `type` is `slack`, this is a `SlackTriggerConfig`. When `type` is `sentry`, this is a `SentryTriggerConfig`. When `type` is `custom`, this is a `CustomTriggerConfig` (empty object).
      - CronTriggerConfig — Configuration for a cron (scheduled) trigger
        - `schedule` string, required — Cron expression (e.g. "0 9 * * 1-5" for weekdays at 9am UTC)
        - `timezone` string — IANA timezone for the schedule (defaults to UTC)
      - GitHubTriggerConfig — Configuration for a GitHub event trigger
        - `event` 'pull_request.opened' | 'pull_request.synchronize' | 'pull_request.merged' | 'pull_request.closed' | 'pull_request.command', required — The GitHub event to listen for
        - `repository_ids` string[] — Optional filter: only fire for events from these repositories. If omitted, fires for all repositories.
        - `group_pr_events` boolean — When true, later `pull_request.opened`, `pull_request.synchronize`, or `pull_request.command` events for a PR that already has a workspace from an earlier run of this automation are routed to that workspace as a follow-up message instead of spawning a new one. Only meaningful for the opened, synchronize, and command events.
        - `excluded_actors` string[] — Optional exclusion list: events sent by these GitHub usernames never fire the automation (e.g. `dependabot[bot]`). Matching is case-insensitive and ignores a leading `@`.
      - GitLabTriggerConfig — Configuration for a GitLab merge request event trigger
        - `event` 'merge_request.opened' | 'merge_request.updated' | 'merge_request.merged' | 'merge_request.closed', required — The GitLab event to listen for
        - `repository_ids` string[] — Optional filter: only fire for events from these GitLab projects. If omitted, fires for all projects.
        - `group_pr_events` boolean — When true, later `merge_request.opened` or `merge_request.updated` events for an MR that already has a workspace from an earlier run of this automation are routed to that workspace as a follow-up message instead of spawning a new one. Only meaningful for the opened and updated events.
        - `excluded_actors` string[] — Optional exclusion list: events sent by these GitLab usernames never fire the automation. Matching is case-insensitive and ignores a leading `@`.
      - SlackTriggerConfig — Configuration for a Slack event trigger
        - `event` 'message', required — The Slack event to listen for
        - `channel_ids` string[] — Optional filter: only fire for events from these Slack channels. If omitted, fires for all channels.
        - `group_thread_replies` boolean — When true (default), thread replies flow to the same workspace as the root message instead of spawning new ones.
      - SentryTriggerConfig — Configuration for a Sentry event trigger
        - `event` 'event_alert.triggered' | 'issue.created' | 'error.created', required — The Sentry event to listen for
        - `project_slugs` string[] — Optional filter: only fire for events from these Sentry project slugs. If omitted, fires for all projects.
        - `min_level` 'debug' | 'info' | 'warning' | 'error' | 'fatal' — Optional minimum severity level (inclusive). If omitted, fires for all levels.
      - CustomTriggerConfig — Configuration for a custom webhook trigger. The config is intentionally empty: the automation's generated `webhook_token` is the only thing that needs to be stored.
  - `prompt` string, required — The instruction sent to the coding agent when the automation fires
  - `debounce_seconds` integer, nullable — Optional per-automation debounce window in seconds. When greater than 0, bursty trigger events update one pending run for this automation and the latest payload runs after the automation stops receiving events for this many seconds. Null or 0 disables debouncing.
  - `environment_id` string, uuid, required — ID of the environment this automation runs in. Required. The environment supplies the repository (or repository set) and resolved env vars / MCPs / skills.
  - `enabled` boolean — Whether the automation should be active (defaults to true)
  - `workspace_lifecycle_policy` 'default' | 'archive_when_done' | 'sleep_when_done' | 'delete_after_inactivity' — Lifecycle policy for workspaces created by this automation
  - `workspace_auto_stop_minutes` integer — Inactivity timeout in minutes for default keep-alive and delete_after_inactivity policies
  - `workspace_size` 'small' | 'large' — Compute size for every workspace this automation fires off. `small` (2 vCPU, 8 GB memory, 20 GB disk) bills at $0.008/min; `large` (4 vCPU, 16 GB memory, 32 GB disk) bills at $0.016/min. Defaults to `small`.
  - `config` WorkspaceConfig — Workspace behavior configuration. Missing capabilities and preferences default to disabled.
    - `capabilities` object — Actions this workspace is allowed to perform. Automations snapshot this config onto each workspace they create; API-created replicas can set it at creation time.
      - `pr_followups` boolean — Whether matching pull requests can receive Replicas follow-up actions. Defaults to true for workspaces created from the dashboard, Slack, Linear, GitHub, or the API, and to false for workspaces created from an automation. When enabled, later CI and review-comment replies can route back to this workspace.
    - `preferences` object — Workspace behavior preferences that do not grant new action permissions.
      - `keep_open_on_pr_merge` boolean — Whether the workspace should remain open after its last tracked PR is merged. Defaults to false.
      - `keep_open_on_pr_close` boolean — Whether the workspace should remain open after its last tracked PR is closed without merging. Defaults to false.
    - `provisioning_error` object — Setup/provisioning or wake/resume failure captured when the workspace remains queryable in `error` status. Some wake/resume failures can be retried; the `error` status can also represent an unrecoverable sandbox failure.
      - `message` string — Underlying setup failure message, such as repository clone/auth errors.
  - `agent_provider` 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'null', nullable — Coding agent override. Null inherits the organization default.
  - `model` string, nullable — Model override. Requires `agent_provider` when set.
  - `thinking_level` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'ultracode' | 'null', nullable — Thinking/reasoning level override. `ultra` is Codex-only; `ultracode` is Claude Code-only.
  - `plan_mode` boolean — Run automation messages in plan mode.
  - `goal_mode` boolean, nullable — Set automation messages as Codex goals. Null inherits the resolved agent default; false explicitly disables it. Only applies when the resolved agent is Codex.
  - `fast_mode` boolean, nullable — Run automation messages in fast mode. Null inherits the resolved agent default; false explicitly disables it.

## Response `201`

Automation created successfully

- AutomationResponse — Response containing a single automation
  - `automation` AutomationRecord, required — An automation record
    - `id` string, uuid, required — Unique identifier for the automation
    - `organization_id` string, uuid, required — Organization that owns this automation
    - `name` string, required — Human-readable name for the automation
    - `description` string, nullable, required — Optional description
    - `triggers` AutomationTrigger[], required — Triggers that fire this automation
      - `type` 'cron' | 'github' | 'gitlab' | 'slack' | 'sentry' | 'custom', required — The trigger type
      - `config` union, required — Trigger-specific configuration. When `type` is `cron`, this is a `CronTriggerConfig`. When `type` is `github`, this is a `GitHubTriggerConfig`. When `type` is `gitlab`, this is a `GitLabTriggerConfig`. When `type` is `slack`, this is a `SlackTriggerConfig`. When `type` is `sentry`, this is a `SentryTriggerConfig`. When `type` is `custom`, this is a `CustomTriggerConfig` (empty object).
        - CronTriggerConfig — Configuration for a cron (scheduled) trigger
          - `schedule` string, required — Cron expression (e.g. "0 9 * * 1-5" for weekdays at 9am UTC)
          - `timezone` string — IANA timezone for the schedule (defaults to UTC)
        - GitHubTriggerConfig — Configuration for a GitHub event trigger
          - `event` 'pull_request.opened' | 'pull_request.synchronize' | 'pull_request.merged' | 'pull_request.closed' | 'pull_request.command', required — The GitHub event to listen for
          - `repository_ids` string[] — Optional filter: only fire for events from these repositories. If omitted, fires for all repositories.
          - `group_pr_events` boolean — When true, later `pull_request.opened`, `pull_request.synchronize`, or `pull_request.command` events for a PR that already has a workspace from an earlier run of this automation are routed to that workspace as a follow-up message instead of spawning a new one. Only meaningful for the opened, synchronize, and command events.
          - `excluded_actors` string[] — Optional exclusion list: events sent by these GitHub usernames never fire the automation (e.g. `dependabot[bot]`). Matching is case-insensitive and ignores a leading `@`.
        - GitLabTriggerConfig — Configuration for a GitLab merge request event trigger
          - `event` 'merge_request.opened' | 'merge_request.updated' | 'merge_request.merged' | 'merge_request.closed', required — The GitLab event to listen for
          - `repository_ids` string[] — Optional filter: only fire for events from these GitLab projects. If omitted, fires for all projects.
          - `group_pr_events` boolean — When true, later `merge_request.opened` or `merge_request.updated` events for an MR that already has a workspace from an earlier run of this automation are routed to that workspace as a follow-up message instead of spawning a new one. Only meaningful for the opened and updated events.
          - `excluded_actors` string[] — Optional exclusion list: events sent by these GitLab usernames never fire the automation. Matching is case-insensitive and ignores a leading `@`.
        - SlackTriggerConfig — Configuration for a Slack event trigger
          - `event` 'message', required — The Slack event to listen for
          - `channel_ids` string[] — Optional filter: only fire for events from these Slack channels. If omitted, fires for all channels.
          - `group_thread_replies` boolean — When true (default), thread replies flow to the same workspace as the root message instead of spawning new ones.
        - SentryTriggerConfig — Configuration for a Sentry event trigger
          - `event` 'event_alert.triggered' | 'issue.created' | 'error.created', required — The Sentry event to listen for
          - `project_slugs` string[] — Optional filter: only fire for events from these Sentry project slugs. If omitted, fires for all projects.
          - `min_level` 'debug' | 'info' | 'warning' | 'error' | 'fatal' — Optional minimum severity level (inclusive). If omitted, fires for all levels.
        - CustomTriggerConfig — Configuration for a custom webhook trigger. The config is intentionally empty: the automation's generated `webhook_token` is the only thing that needs to be stored.
    - `prompt` string, required — The instruction sent to the coding agent when the automation fires
    - `debounce_seconds` integer, nullable, required — Optional per-automation debounce window in seconds. When set and greater than 0, bursty trigger events update one pending run for this automation and the latest payload runs after the automation stops receiving events for this many seconds. Null or 0 disables debouncing.
    - `environment_id` string, uuid, required — ID of the environment this automation runs in. The environment supplies the repository (or repository set) and the env vars / MCPs / skills layered on top of the org-wide Global environment.
    - `enabled` boolean, required — Whether the automation is active
    - `webhook_token` string, nullable, required — Unique token for the automation's custom webhook. Present only when a `custom` trigger is configured. The public webhook URL is `POST /v1/automations/webhook/{webhook_token}`. Treat the token like an API key: the URL alone is enough to fire the automation.
    - `cron_expression` string, nullable, required — Derived cron expression (from the cron trigger, if any)
    - `cron_timezone` string, nullable, required — Timezone for the cron schedule
    - `cron_next_fire_at` string, date-time, nullable, required — Next scheduled fire time for cron automations
    - `user_id` string, uuid, nullable, required — User ID for personal automations, null for org-owned automations
    - `created_by` string, uuid, nullable, required — User who created the automation
    - `workspace_lifecycle_policy` 'default' | 'archive_when_done' | 'sleep_when_done' | 'delete_after_inactivity', required — Lifecycle policy for workspaces created by this automation
    - `workspace_auto_stop_minutes` integer, nullable, required — Inactivity timeout in minutes (3-1440) for default keep-alive and delete_after_inactivity policies
    - `workspace_size` 'small' | 'large' | 'null', nullable, required — Compute size for workspaces fired off by this automation. Defaults to `small` when omitted.
    - `config` WorkspaceConfig, required — Workspace behavior configuration. Missing capabilities and preferences default to disabled.
      - `capabilities` object — Actions this workspace is allowed to perform. Automations snapshot this config onto each workspace they create; API-created replicas can set it at creation time.
        - `pr_followups` boolean — Whether matching pull requests can receive Replicas follow-up actions. Defaults to true for workspaces created from the dashboard, Slack, Linear, GitHub, or the API, and to false for workspaces created from an automation. When enabled, later CI and review-comment replies can route back to this workspace.
      - `preferences` object — Workspace behavior preferences that do not grant new action permissions.
        - `keep_open_on_pr_merge` boolean — Whether the workspace should remain open after its last tracked PR is merged. Defaults to false.
        - `keep_open_on_pr_close` boolean — Whether the workspace should remain open after its last tracked PR is closed without merging. Defaults to false.
      - `provisioning_error` object — Setup/provisioning or wake/resume failure captured when the workspace remains queryable in `error` status. Some wake/resume failures can be retried; the `error` status can also represent an unrecoverable sandbox failure.
        - `message` string — Underlying setup failure message, such as repository clone/auth errors.
    - `agent_provider` 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'null', nullable, required — Coding agent override for this automation. Null inherits the organization default.
    - `model` string, nullable, required — Model override for this automation. Null uses the agent default.
    - `thinking_level` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'ultracode' | 'null', nullable, required — Thinking/reasoning level override for this automation. `ultra` is Codex-only; `ultracode` is Claude Code-only.
    - `plan_mode` boolean, required — Whether automation messages run in plan mode.
    - `goal_mode` boolean, nullable, required — Whether automation messages are set as Codex goals. Null inherits the resolved agent default; false explicitly disables it. Only applies when the resolved agent is Codex.
    - `fast_mode` boolean, nullable, required — Whether automation messages run in fast mode. Null inherits the resolved agent default; false explicitly disables it.
    - `created_at` string, date-time, required — When the automation was created
    - `updated_at` string, date-time, required — When the automation was last updated

## Other responses

- `400` — Bad request - Missing or invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `403` — Automation limit reached for the current plan
- `500` — Internal server error

---

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