Create an agent automation

create_agent_automation

Creates an agent automation on a site, once the person has agreed to its preview.

POST /v1/create_agent_automationScopeconfig:writeMakes changes

An agent automation is a standing instruction the agent carries out on a schedule. Each run reads the one site with read-only tools and emails its report to the person who created it. It cannot change the site, publish it or email anyone else. See Agents.

Call it first with confirm set to false. That returns a preview of the instruction, the schedule, the next runs and what the agent can read, and it creates nothing. Show the preview to the person, and call again with confirm set to true only after they agree.

A site holds at most 3 agent automations, and runs cannot be closer together than 5 minutes. It is refused while the site is locked, and while Modulify has switched off an agent automation on the site.

Request

Call it with a POST to https://api.modulify.ai/v1/create_agent_automation, sending the inputs below as a JSON object. The token needs the config:write scope.

It makes changes, so send an Idempotency-Key header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

curl -X POST https://api.modulify.ai/v1/create_agent_automation \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","name":"NAME","instruction":"INSTRUCTION","schedule":{}}'

Over MCP, the same method is the create_agent_automation tool.

Inputs

Input Type Required Description
projectId string Yes The site id.
name string Yes What to call the automation, up to 64 characters.
instruction string Yes What the agent should do on each run, written as a plain request, up to 2,000 characters. It is sent with the site's name, the time of the run and the schedule's timezone.
schedule object Yes When it runs. The same shape as the schedule of create_site_cron: a Kind of hourly, daily, weekly, monthly or cron, the fields that kind uses, and an optional Timezone. Without one it runs in UTC.
confirm boolean No false by default, which returns the preview. true creates the automation.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.