Modem

Create Automation

create_automation

Create an automation. Useful for reminders, follow-ups, periodic tasks, or event-driven workflows per user. Returns the full automation object including computed nextRunAt.

Schedule field accepts 5 formats:

{type: "at", at: "<ISO 8601>"} - one-time execution (must be future)
{type: "every", unit: "minutes"|"hours", n: } - recurring interval (min 30 min)
{type: "cron", expr: ""} - cron schedule (min 30 min between runs)
{type: "rrule", rrule: ""} - iCalendar rule (min 30 min between occurrences)
{type: "event", events: ["", ...]} - event-driven (triggers immediately on ANY of the listed events, up to 20; each occurrence fires one run carrying just that event's payload). {type: "event", event: ""} (single string field) is a legacy alias for a one-event array and is still accepted, but "events" is canonical for new automations. GitHub PR triggers may also include {targetBranches: ["main", ...]} to run only when the PR's target branch matches one of those case-sensitive names or * patterns (e.g. "release/*").
- matches zero or more characters, including slashes. Omit it to match every target branch. An activity event shares its schedule only with other conversation activity events (chat.activity, call.activity, support_ticket.activity, feedback.activity, social_post.activity); pull_request.activity and issue.activity stand alone. An activity schedule may add {filter: ""} to run only for matching events, e.g. "source.name in ['zendesk', 'intercom'] && author.role == 'customer'". On several conversation events it may name only source.name, placement, author.role and topic.priority_change. The filter field's schema lists the grammar and each event's fields. Optionally add {delaySeconds: <int 1..604800>} to an event schedule to defer the run until N seconds after the trigger event fires (e.g. 1800 = 30 minutes later; max 604800 = 7 days). Omit for immediate execution. A delayed run is cancelled if the automation is disabled during the wait. Optionally add {condition: "<natural language, up to 2000 chars>"} to run only for events that satisfy it (e.g. "the customer is on the Enterprise plan"); Modem checks it against each event's payload before running. A filter or condition also satisfies an event that requires a channel or product scope. conditionMode and conditionSchemaVersion are set by Modem and ignored on input.

Available events: github.pr.created, github.pr.merged, github.pr.dismissed, github.issue.closed, gitlab.mr.created, gitlab.mr.merged, gitlab.mr.closed, topic.created, topic.priority.high, stripe.customer.created, stripe.subscription.created, stripe.subscription.canceled, stripe.subscription.trial_ending, stripe.invoice.payment_failed, sentry.feedback.created, feedback.created, topic.group.added, topic.group.updated, chat.activity, call.activity, support_ticket.activity, feedback.activity, social_post.activity, pull_request.activity, issue.activity

Prompt guidelines: must be self-contained with ALL context the executing agent needs. Write in plain language. Structure as a clear plan with steps. Include external service IDs (Slack channel/user IDs). Never include database internals.

MODEL LEVEL GUIDELINES: Pick the model level that best matches the automation's complexity. Do NOT default to "high".

"low" (Fast): Lookup/linking tasks, simple data retrieval, pattern matching, forwarding/routing. Examples: linking PRs to topics, tagging items with keywords, posting simple notifications, checking statuses.
"med" (Balanced): Summaries of structured data, daily digests, status rollups, template-based reports. Examples: daily standup summaries, weekly metric rollups, changelog digests, review request roundups.
"high" (Smart): Complex analysis, nuanced writing, multi-step reasoning, customer-facing content, creative tasks. Examples: user health analysis, strategic recommendations, personalized outreach, complex triage decisions. When in doubt, use "med" (Balanced).

timezone is required and must be an IANA time zone such as America/New_York. You become its owner. The automation's dashboard page is https://app.modem.dev/<org-slug>/automations/<id>. Before your first call, read the skill: modem_skills({ name: "automations" }).

Input Schema

Name	Required	Description
`name`	Yes	Human-friendly name for the workflow run, e.g. "weekly_summary_for_alex"
`prompt`	No	Natural language instructions for what the automation should do. Required unless outcome is a webhook.
`enabled`	No	Whether the automation should be enabled to run on its schedule.
`outcome`	No	What the automation does when it fires. Omit for the default: run the Modem agent with the prompt. {type: "webhook", url} POSTs the trigger event to the URL instead of running the agent; the prompt, model level, capabilities and output channels are then unused. The signing secret receivers verify deliveries with is shown on the automation's page in the Modem dashboard; the API never returns it.
`schedule`	Yes	Defines when an automation should run.
`timezone`	Yes
`modelLevel`	No	Model level: "low" (Fast), "med" (Balanced), or "high" (Smart).
`capabilityMode`	No	Capability mode: "all" (all visible capabilities, including ones added later) or "custom" (only listed capabilities). If omitted on create, defaults to "custom" with a snapshot of every currently-available capability so the automation does not silently inherit future integrations.
`outputChannels`	No	Allowed output channels and optional destination restrictions.
`allowedCapabilities`	No	Capability keys to enable when capabilityMode is "custom". On create, providing this field implies custom mode when capabilityMode is omitted. An empty array means core-only.
`sourceDefaultTaskSlug`	No	Template-library default task slug this automation is being created from, if any.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 30, 2026

addedInput schema / properties / outcome

Added value: +{
+  "description": "What the automation does when it fires. Omit for the default: run the Modem agent with the prompt. {type: \"webhook\", url} POSTs the trigger event to the URL instead of running the agent; the prompt, model level, capabilities and output channels are then unused. The signing secret receivers verify deliveries with is shown on the automation's page in the Modem dashboard; the API never returns it.",
+  "oneOf": [
+    {
+      "properties": {
+        "type": {
+          "const": "agent",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "type": "object"
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "webhook",
+          "type": "string"
+        },
+        "url": {
+          "description": "HTTPS URL Modem POSTs a Standard Webhooks-signed JSON envelope to each time the automation fires.",
+          "maxLength": 2048,
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "url"
+      ],
+      "type": "object"
+    }
+  ]
+}

changedInput schema / properties / prompt / description

Previous value: -"Natural language instructions for what the automation should do."New value: +"Natural language instructions for what the automation should do. Required unless outcome is a webhook."

changedInput schema / required

Previous value: -[
-  "name",
-  "timezone",
-  "schedule",
-  "prompt"
-]New value: +[
+  "name",
+  "timezone",
+  "schedule"
+]

Changed1 schema field changedOct 27, 2026