Create automation

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.

POST/automations

Authorization

AuthorizationBearer token · headerrequired

Organization API key (modem_…).

Header parameters

Idempotency-Keystring

Replays a successful mutating request for 24 hours. Reuse with a different payload returns 409.

max length 255

Request body

requiredapplication/json

Any of:

object

allowedCapabilitiesstring[] | null

Explicit capability keys when capabilityMode is custom. Null means all.

Show properties

Any of:

string[]

Array of string

string

null

null

capabilityModestring

Whether this task uses all visible capabilities or a custom subset.

Allowed:allcustom

enabledboolean

modelLevelstring

Persisted model level for automation execution.

Allowed:highlowmed

namestringrequired

min length 1

promptstringrequired

min length 1 · max length 130000

scheduleobjectrequired

Show properties

Any of:

object

exprstringrequired

min length 1

typeanyrequired

object

rrulestringrequired

min length 1

typeanyrequired

object

atstring<date-time>required

typeanyrequired

object

nintegerrequired

typeanyrequired

unitstringrequired

Allowed:hoursminutes

object

delaySecondsinteger

min 1 · max 604800

eventsstring[]required

min items 1 · max items 20

targetBranchesstring[]

min items 1

typeanyrequired

templateSlugstring

matches ^[a-z0-9-]+$

timezonestringrequired

min length 1

object

allowedCapabilitiesstring[] | null

Explicit capability keys when capabilityMode is custom. Null means all.

Show properties

Any of:

string[]

Array of string

string

null

null

capabilityModestring

Whether this task uses all visible capabilities or a custom subset.

Allowed:allcustom

enabledboolean

modelLevelstring

Persisted model level for automation execution.

Allowed:highlowmed

namestringrequired

min length 1

promptstringrequired

min length 1 · max length 130000

scheduleobjectrequired

Show properties

Any of:

object

exprstringrequired

min length 1

typeanyrequired

object

rrulestringrequired

min length 1

typeanyrequired

object

atstring<date-time>required

typeanyrequired

object

nintegerrequired

typeanyrequired

unitstringrequired

Allowed:hoursminutes

object

delaySecondsinteger

min 1 · max 604800

eventsstring[]required

min items 1 · max items 20

targetBranchesstring[]

min items 1

typeanyrequired

sourceChannelIdstringrequired

min length 1

sourceNamestringrequired

Allowed:discordslack

templateSlugstring

matches ^[a-z0-9-]+$

timezonestringrequired

min length 1

Responses

200

allowedCapabilitiesstring[] | nullrequired

Explicit capability keys when capabilityMode is custom. Null means all.

Show properties

Any of:

string[]

Array of string

string

null

null

capabilityModestringrequired

Whether this task uses all visible capabilities or a custom subset.

Allowed:allcustom

createdAtstring<date-time>

Timestamp when the task was created.

enabledbooleanrequired

Whether the task is actively being scheduled.

idstring<uuid>required

lastAttemptAtstring<date-time> | null

Timestamp when the most recent execution attempt started, including manual runs.

Show properties

Any of:

string<date-time>

string<date-time>

null

null

lastErrorMessagestring | nullrequired

Most recent error message if status is error.

Show properties

Any of:

string

string

null

null

lastRunAtstring<date-time> | null

Timestamp of the most recent scheduler-managed execution, used to calculate the next run.

Show properties

Any of:

string<date-time>

string<date-time>

null

null

modelLevelstringrequired

Persisted model level for automation execution.

Allowed:highlowmed

namestringrequired

Human-readable name for the automation.

min length 1

nextRunAtstring<date-time> | null

Timestamp of the next scheduled execution.

Show properties

Any of:

string<date-time>

string<date-time>

null

null

outputChannelsobject[]required

min items 1

Show properties

Array of object

channelstringrequired

Allowed:discordemailmsteamsslack

destinationsstring[] | nullrequired

Show properties

Any of:

string[]

Array of string

string

null

null

modestringrequired

Allowed:any-internalanyspecific

promptstringrequired

AI prompt or instructions executed when the task runs.

min length 1

scheduleobjectrequired

Show properties

Any of:

object

exprstringrequired

min length 1

typeanyrequired

object

rrulestringrequired

min length 1

typeanyrequired

object

atstring<date-time>required

typeanyrequired

object

nintegerrequired

typeanyrequired

unitstringrequired

Allowed:hoursminutes

object

delaySecondsinteger

min 1 · max 604800

eventsstring[]required

min items 1 · max items 20

targetBranchesstring[]

min items 1

typeanyrequired

statusstringrequired

Current health status of the automation.

Allowed:completederrorhealthypaused

templateSlugstring | nullrequired

Show properties

Any of:

string

string

null

null

timezonestringrequired

IANA timezone identifier for schedule evaluation.

min length 1

updatedAtstring<date-time>

Timestamp when the task was last updated.

400

Invalid request (validation failed).

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

401

Missing or invalid API key.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

403

The API key does not have access to this resource.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

404

The requested resource was not found.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

409

The request conflicts with an existing resource or idempotency operation.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

429

Rate limit exceeded.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

500

Internal server error.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

Idempotency-KeyheaderReplays a successful mutating request for 24 hours. Reuse with a different payload returns 409.

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.modem.dev/v1/automations' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "allowedCapabilities": [
    "string"
  ],
  "capabilityMode": "all",
  "enabled": true,
  "modelLevel": "high",
  "name": "string",
  "prompt": "string",
  "schedule": {
    "expr": "string",
    "type": "cron"
  },
  "templateSlug": "string",
  "timezone": "string"
}'

const response = await fetch("https://api.modem.dev/v1/automations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"allowedCapabilities\": [\n    \"string\"\n  ],\n  \"capabilityMode\": \"all\",\n  \"enabled\": true,\n  \"modelLevel\": \"high\",\n  \"name\": \"string\",\n  \"prompt\": \"string\",\n  \"schedule\": {\n    \"expr\": \"string\",\n    \"type\": \"cron\"\n  },\n  \"templateSlug\": \"string\",\n  \"timezone\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://api.modem.dev/v1/automations",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"allowedCapabilities\": [\n    \"string\"\n  ],\n  \"capabilityMode\": \"all\",\n  \"enabled\": true,\n  \"modelLevel\": \"high\",\n  \"name\": \"string\",\n  \"prompt\": \"string\",\n  \"schedule\": {\n    \"expr\": \"string\",\n    \"type\": \"cron\"\n  },\n  \"templateSlug\": \"string\",\n  \"timezone\": \"string\"\n}",
)

Response

{
  "allowedCapabilities": [
    "string"
  ],
  "capabilityMode": "all",
  "createdAt": "2019-08-24T14:15:22Z",
  "enabled": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "lastAttemptAt": "2019-08-24T14:15:22Z",
  "lastErrorMessage": "string",
  "lastRunAt": "2019-08-24T14:15:22Z",
  "modelLevel": "high",
  "name": "string",
  "nextRunAt": "2019-08-24T14:15:22Z",
  "outputChannels": [
    {
      "channel": "discord",
      "destinations": [
        "string"
      ],
      "mode": "any-internal"
    }
  ],
  "prompt": "string",
  "schedule": {
    "expr": "string",
    "type": "cron"
  },
  "status": "completed",
  "templateSlug": "string",
  "timezone": "string",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}