---
title: "Create automation"
method: POST
path: "/automations"
tags: ["Automations"]
---

# Create automation

`POST /automations`

## Request

- Base URL: `https://api.modem.dev/v1`
- URL: `https://api.modem.dev/v1/automations`
- Auth: HTTP bearer

Create an automation for the API key's organization. Modem assigns the organization's earliest owner.

Provide a complete automation definition. Event schedules accept canonical registered event names only.
GitHub PR event schedules can include targetBranches with exact names or * wildcards; omit it to match
every target branch. A target-branch filter is only valid when every configured event is a GitHub PR event.
To send output to Slack or Discord, provide sourceName and sourceChannelId together. Otherwise Modem uses
the organization's saved default output destination. Requests fail when no valid destination is available.

This operation supports Idempotency-Key and accepts organization API keys only; service JWTs are rejected.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `allowedCapabilities` string[], nullable: Explicit capability keys when capabilityMode is custom. Null means all.
    - `capabilityMode` 'all' | 'custom': Whether this task uses all visible capabilities or a custom subset.
    - `enabled` boolean
    - `modelLevel` 'high' | 'low' | 'med': Persisted model level for automation execution.
    - `name` string, required
    - `prompt` string, required
    - `schedule` union, required
      - object
        - `expr` string, required
        - `type` 'cron', required
      - object
        - `rrule` string, required
        - `type` 'rrule', required
      - object
        - `at` string, date-time, required
        - `type` 'at', required
      - object
        - `n` integer, required
        - `type` 'every', required
        - `unit` 'hours' | 'minutes', required
      - object
        - `condition` string
        - `delaySeconds` integer
        - `events` string[], required
        - `targetBranches` string[]
        - `type` 'event', required
    - `templateSlug` string
    - `timezone` string, required
  - object
    - `allowedCapabilities` string[], nullable: Explicit capability keys when capabilityMode is custom. Null means all.
    - `capabilityMode` 'all' | 'custom': Whether this task uses all visible capabilities or a custom subset.
    - `enabled` boolean
    - `modelLevel` 'high' | 'low' | 'med': Persisted model level for automation execution.
    - `name` string, required
    - `prompt` string, required
    - `schedule` union, required
      - object
        - `expr` string, required
        - `type` 'cron', required
      - object
        - `rrule` string, required
        - `type` 'rrule', required
      - object
        - `at` string, date-time, required
        - `type` 'at', required
      - object
        - `n` integer, required
        - `type` 'every', required
        - `unit` 'hours' | 'minutes', required
      - object
        - `condition` string
        - `delaySeconds` integer
        - `events` string[], required
        - `targetBranches` string[]
        - `type` 'event', required
    - `sourceChannelId` string, required
    - `sourceName` 'discord' | 'slack', required
    - `templateSlug` string
    - `timezone` string, required

## Response `200`

OK

- object
  - `allowedCapabilities` string[], nullable, required: Explicit capability keys when capabilityMode is custom. Null means all.
  - `capabilityMode` 'all' | 'custom', required: Whether this task uses all visible capabilities or a custom subset.
  - `createdAt` string, date-time: Timestamp when the task was created.
  - `enabled` boolean, required: Whether the task is actively being scheduled.
  - `id` string, uuid, required
  - `lastAttemptAt` string, date-time, nullable: Timestamp when the most recent execution attempt started, including manual runs.
  - `lastErrorMessage` string, nullable, required: Most recent error message if status is error.
  - `lastRunAt` string, date-time, nullable: Timestamp of the most recent scheduler-managed execution, used to calculate the next run.
  - `modelLevel` 'high' | 'low' | 'med', required: Persisted model level for automation execution.
  - `name` string, required: Human-readable name for the automation.
  - `nextRunAt` string, date-time, nullable: Timestamp of the next scheduled execution.
  - `outputChannels` object[], required
    - `channel` 'discord' | 'email' | 'msteams' | 'slack', required
    - `destinations` string[], nullable, required
    - `mode` 'any-internal' | 'any' | 'specific', required
  - `prompt` string, required: AI prompt or instructions executed when the task runs.
  - `schedule` union, required
    - object
      - `expr` string, required
      - `type` 'cron', required
    - object
      - `rrule` string, required
      - `type` 'rrule', required
    - object
      - `at` string, date-time, required
      - `type` 'at', required
    - object
      - `n` integer, required
      - `type` 'every', required
      - `unit` 'hours' | 'minutes', required
    - object
      - `condition` string
      - `delaySeconds` integer
      - `events` string[], required
      - `targetBranches` string[]
      - `type` 'event', required
  - `status` 'completed' | 'error' | 'healthy' | 'paused', required: Current health status of the automation.
  - `templateSlug` string, nullable, required
  - `timezone` string, required: IANA timezone identifier for schedule evaluation.
  - `updatedAt` string, date-time: Timestamp when the task was last updated.

## Other responses

- `400`: Invalid request (validation failed).
- `401`: Missing or invalid API key.
- `403`: The API key does not have access to this resource.
- `404`: The requested resource was not found.
- `409`: The request conflicts with an existing resource or idempotency operation.
- `429`: Rate limit exceeded.
- `500`: Internal server error.

---

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