Automations API

Your automations can be managed outside the app: from a conversation with Claude or ChatGPT connected to n8v, or from your own scripts with an API key. List them, read one in full, see why its runs failed, create one, change its prompt, model or schedule, pause and resume it, run it now and delete it.

Every answer says whether the automation's model can still run. An automation whose model was turned off, or that its provider stopped serving, carries a warning in plain words, so an assistant can find it and fix it in the same conversation.

Access

Two scopes, for API keys and connected assistants alike:

automations:write does not include reading: a key that should find an automation and then change it needs both.

• An API key: in Settings, API, click Create key and tick the scopes under Automations. The key's repositories bound what it sees and changes.
• An assistant: connect Claude or ChatGPT as in MCP Setup and approve See your automations and Manage your automations. An API key with these scopes works as the bearer token for https://n8v.online/mcp too.

Calls and tools

The automation object

Every call that answers with an automation answers with this shape (shortened here):

{
  "automation": {
    "id": "9fad8d64-e794-460e-8074-62e6456ba8a1",
    "name": "Weekly review",
    "description": null,
    "enabled": true,
    "url": "https://n8v.online/automations/9fad8d64-e794-460e-8074-62e6456ba8a1",
    "trigger": "schedule",
    "schedule": {
      "cron": "0 2 * * 5",
      "timezone": "Europe/Lisbon",
      "frequency": "weekly",
      "time": "02:00",
      "days": ["fri"],
      "description": "At 02:00 AM, only on Friday (Europe/Lisbon)",
      "next_run_at": "2026-11-13T02:00:00.000Z"
    },
    "github": null,
    "webhook": null,
    "action": "prompt",
    "prompt": "Review last week's merged pull requests and list what was left behind",
    "model": {
      "id": "gpt-5.5-xhigh",
      "name": "GPT-5.5 X-High",
      "status": "refused",
      "message": "The last run (2026-11-06) was refused for GPT-5.5 X-High: The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account."
    },
    "repo": "owner/name",
    "branch": "main",
    "new_chat_each_run": true,
    "follow_up": null,
    "archive_runs": false,
    "skip_setup": false,
    "checkpoints": true,
    "run_count": 32,
    "last_run_at": "2026-11-06T02:00:42.000Z",
    "next_run_at": "2026-11-13T02:00:00.000Z",
    "last_run": {
      "chat_id": "40fb1421-6b1e-4f43-9d0a-1f0d8c0b2a77",
      "status": "complete",
      "at": "2026-11-06T02:00:42.000Z",
      "error": {
        "code": "agent_generic_error",
        "message": "The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account.",
        "model_refused": true
      }
    },
    "warnings": [
      "The last run (2026-11-06) was refused for GPT-5.5 X-High: The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account."
    ]
  }
}

Schedule

A schedule takes a timezone (IANA, such as Europe/Amsterdam) and either cron or the fields of the app's schedule picker, never both:

{ "timezone": "Europe/Amsterdam", "frequency": "weekly", "time": "09:00", "days": ["mon", "thu"] }

Answers give both forms, whichever was sent: cron, the picker's fields, the schedule in words as description, and next_run_at. The plan's schedule rules apply as in the app: a schedule it does not allow answers 422 automation_refused with the reason. On PATCH, schedule replaces the schedule; leave out timezone to keep the current one.

Model health

model says which model runs and whether it still can:

A refusal counts only while the model is the one the run asked for: change the model and the warning goes, even before the next run.

Writes check the model before they save. Creating or changing an automation with a model the account cannot run, and running one now, answers 422 model_unavailable, with a hint that points to the models you can use. Leaving out model on create runs your default model, which must be one the account can run today. A refused model is not blocked: the provider may serve it again, so the automation keeps it until you change it. Running one now still starts it, and the answer's warnings says it was refused last time.

In the app, an automation whose model cannot run reads Model cannot run on its card, and its page says why, with the same words.

Follow-up in the same chat

Each run starts a new chat. follow_up continues that chat after the run, like Recurring follow-up in the app:

Send "follow_up": null to turn it off. A pull request or issue automation with a follow-up needs "auto_archive_on_complete": false in github, as in the app; otherwise the write answers 422 automation_refused.

GitHub triggers

For pull_request, issue and github_mention, github holds the trigger's options. On create, what is left out takes the app's defaults; on PATCH, what is left out stays as it was.

Include only authors and bots you trust: see Security considerations.

Endpoints

Base URL https://n8v.online/api/v1, authentication and errors as in the API.

List automations

GET /api/v1/automations, needs automations:read. Every automation in the key's repositories, up to 200.

curl -sS "https://n8v.online/api/v1/automations?enabled=true" \
  -H "Authorization: Bearer $N8V_API_KEY"

{
  "automations": [
    {
      "id": "9fad8d64-e794-460e-8074-62e6456ba8a1",
      "name": "Weekly review",
      "enabled": true,
      "trigger": "schedule",
      "model": { "id": "gpt-5.5-xhigh", "name": "GPT-5.5 X-High", "status": "refused", "message": "The last run (2026-11-06) was refused for GPT-5.5 X-High: ..." },
      "next_run_at": "2026-11-13T02:00:00.000Z",
      "warnings": ["The last run (2026-11-06) was refused for GPT-5.5 X-High: ..."]
    }
  ]
}

(Shortened: each entry is a full automation object.) To find the ones that need attention, look for a non-empty warnings.

Read an automation

GET /api/v1/automations/{id}, needs automations:read. Answers 200 with {"automation": {...}}.

curl -sS https://n8v.online/api/v1/automations/9fad8d64-e794-460e-8074-62e6456ba8a1 \
  -H "Authorization: Bearer $N8V_API_KEY"

Create an automation

POST /api/v1/automations, needs automations:write. Checked as the app checks it: your plan's limits on active automations and schedules, the repository and branch on GitHub, and the model.

Any other field answers 400 invalid_request, with the field in param.

curl -sS --fail-with-body --retry 3 --retry-max-time 120 \
  -X POST https://n8v.online/api/v1/automations \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{
    "name": "Morning triage",
    "repo": "owner/name",
    "prompt": "Triage the issues opened since yesterday and label them",
    "model": "sonnet-5",
    "schedule": {
      "timezone": "Europe/Amsterdam",
      "frequency": "weekdays",
      "time": "08:30"
    }
  }'

{
  "automation": {
    "id": "c2a7e0b4-5d1f-4b9e-8a63-0e4f2d7b9c15",
    "name": "Morning triage",
    "enabled": true,
    "trigger": "schedule",
    "schedule": {
      "cron": "30 8 * * 1-5",
      "timezone": "Europe/Amsterdam",
      "frequency": "weekdays",
      "time": "08:30",
      "description": "At 08:30 AM, Monday through Friday (Europe/Amsterdam)",
      "next_run_at": "2026-11-09T07:30:00.000Z"
    },
    "model": { "id": "sonnet-5", "name": "Sonnet 5", "status": "ok", "message": null },
    "repo": "owner/name",
    "branch": "main",
    "warnings": []
  }
}

Answers 201. Creating a webhook automation stays in the app, see What stays in the app.

Change an automation

PATCH /api/v1/automations/{id}, needs automations:write. Takes the fields of create, all optional, at least one. Only the fields sent change: a new model keeps the prompt, a new schedule time keeps its timezone. Answers 200 with the automation.

curl -sS --fail-with-body -X PATCH \
  https://n8v.online/api/v1/automations/9fad8d64-e794-460e-8074-62e6456ba8a1 \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonnet-5"}'

• trigger switches between the five triggers above. Moving a webhook automation to another trigger revokes its token, as in the app.
• repo moves the automation to a repository the key allows; otherwise 403 repo_not_allowed.
• prompt, model, follow_up and archive_runs belong to a prompt: on an automation that runs a workflow graph they answer 422 invalid_request.

Pause and resume

POST /api/v1/automations/{id}/pause and POST /api/v1/automations/{id}/resume, need automations:write, no body. Answer 200 with the automation. A paused automation does not run. A resumed schedule waits for its next time; it does not run for the times it missed. Pausing one that is paused, or resuming one that is on, changes nothing and answers the same.

curl -sS -X POST https://n8v.online/api/v1/automations/9fad8d64-e794-460e-8074-62e6456ba8a1/pause \
  -H "Authorization: Bearer $N8V_API_KEY"

Run now

POST /api/v1/automations/{id}/run, needs automations:write. Runs the automation once, like Run now in the app. The run starts an agent in a new chat and spends like any other run. Send an Idempotency-Key, so a retry never starts a second run.

curl -sS --fail-with-body --retry 3 --retry-max-time 120 \
  -X POST https://n8v.online/api/v1/automations/9fad8d64-e794-460e-8074-62e6456ba8a1/run \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Idempotency-Key: $(openssl rand -hex 16)"

{
  "automation_id": "9fad8d64-e794-460e-8074-62e6456ba8a1",
  "chat_id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11"
}

Answers 202. Follow the chat with GET /api/v1/chats/{id}. For a pull request or issue automation, chat_id and url are null: List runs shows its chat once it starts.

Refused with 422 model_unavailable when its model cannot run, and with 422 automation_refused when the app would refuse it too: a github_mention automation (it runs when n8v is mentioned on GitHub), a webhook automation while webhooks are not enabled for the account, or a plan with no automation runs left.

List runs

GET /api/v1/automations/{id}/runs, needs automations:read. The chats it started, newest first.

curl -sS "https://n8v.online/api/v1/automations/9fad8d64-e794-460e-8074-62e6456ba8a1/runs?limit=5" \
  -H "Authorization: Bearer $N8V_API_KEY"

{
  "automation_id": "9fad8d64-e794-460e-8074-62e6456ba8a1",
  "runs": [
    {
      "chat_id": "40fb1421-6b1e-4f43-9d0a-1f0d8c0b2a77",
      "title": "Weekly review",
      "url": "https://n8v.online/task/40fb1421-6b1e-4f43-9d0a-1f0d8c0b2a77",
      "status": "complete",
      "archived": false,
      "at": "2026-11-06T02:00:42.000Z",
      "error": {
        "code": "agent_generic_error",
        "message": "The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account.",
        "model_refused": true
      }
    }
  ],
  "next_cursor": "MjAyNi0xMS0wNlQwMjowMDo0Mi4wMDBafDQwZmIxNDIxLTZiMWUtNGY0My05ZDBhLTFmMGQ4YzBiMmE3Nw"
}

A run can end complete and still carry an error: check error, not status, to tell whether it did its work.

Delete an automation

DELETE /api/v1/automations/{id}, needs automations:write. Deletes it for good, with its webhook token. The chats it started stay. Answers 200:

{ "id": "9fad8d64-e794-460e-8074-62e6456ba8a1", "deleted": true }

To stop it for a while, pause it instead.

Fix an automation whose model stopped working

A weekly automation runs gpt-5.5-xhigh through Codex. The provider stopped serving it on a ChatGPT account, so every run ends without doing its work, while the automation itself looks fine. Ask your assistant: "Why does my weekly review keep failing? Fix it."

- Weekly review (id 9fad8d64-e794-460e-8074-62e6456ba8a1): on, At 02:00 AM, only on Friday (Europe/Lisbon), owner/name@main, model GPT-5.5 X-High. Next run 2026-11-13 02:00 UTC. Last run failed: The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account.
  Warning: The last run (2026-11-06) was refused for GPT-5.5 X-High: The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account.

- 2026-11-06 02:00 UTC, chat 40fb1421-6b1e-4f43-9d0a-1f0d8c0b2a77: complete, failed, refused for its model: The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account.
- 2026-10-30 02:00 UTC, chat 7c3e2a90-1d4b-4f6e-b2a8-5e9f0c1d3b46: complete, failed, refused for its model: The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account.

Updated Weekly review.
- Weekly review (id 9fad8d64-e794-460e-8074-62e6456ba8a1): on, At 02:00 AM, only on Friday (Europe/Lisbon), owner/name@main, model Sonnet 5. Next run 2026-11-13 02:00 UTC. Last run failed: The 'gpt-5.5' model is not supported when using Codex with a ChatGPT account.

# 1. Find the automations that need attention
curl -sS https://n8v.online/api/v1/automations \
  -H "Authorization: Bearer $N8V_API_KEY" |
  jq '.automations[] | select(.warnings | length > 0) | {id, name, warnings}'

# 2. See why its runs failed
curl -sS "https://n8v.online/api/v1/automations/$ID/runs?limit=3" \
  -H "Authorization: Bearer $N8V_API_KEY" |
  jq '.runs[] | {at, error}'

# 3. Pick a model the account can run, and switch to it
curl -sS https://n8v.online/api/v1/models \
  -H "Authorization: Bearer $N8V_API_KEY" |
  jq -r '.models[] | select(.enabled) | .id'

curl -sS --fail-with-body -X PATCH "https://n8v.online/api/v1/automations/$ID" \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonnet-5"}'

Idempotency

Send an Idempotency-Key header on POST /api/v1/automations and POST /api/v1/automations/{id}/run, the two calls that create something. The rules are the API's: a retry with the same key and body answers what the first call did, with 200 and Idempotent-Replayed: true, and creates or runs nothing; a retry that arrives while the first is still running answers 409 idempotency_in_progress; the same key with a different body answers 422 idempotency_conflict; a call that failed frees its key. Keys for runs are separate for every automation.

The other writes are safe to repeat: PATCH sets the same values again, pause and resume change nothing the second time, and a second DELETE answers 404. Over MCP there is no Idempotency-Key: each run_automation call starts a run.

Limits

Automations calls count against the same limit as every other call: 120 a minute per key, across every endpoint, and the same per connected assistant over MCP (a key used over MCP shares its REST budget). Over it: 429 rate_limited with Retry-After over REST, a tool error saying when to try again over MCP. Bodies are up to 256 KB. See Limits.

Your plan's own limits hold as in the app, such as the number of active automations, the schedules it allows and its automation runs. Reaching one answers 422 automation_refused, with the app's words in message.

Repositories

A key limited to some repositories works on automations in those repositories only:

• An automation in another repository does not exist for the key: reading, changing, running or deleting it answers 404 automation_not_found, the same as an id that does not exist, and listing leaves it out.
• Creating an automation in another repository, or moving one there with repo, answers 403 repo_not_allowed.

Connected assistants act with all the repositories your GitHub account can reach.

Errors

The errors these calls add to the API's:

{
  "error": {
    "code": "model_unavailable",
    "message": "GPT-5.5 X-High needs a connected ChatGPT subscription.",
    "param": "model",
    "hint": "GET /api/v1/models lists every model and whether this account can use it."
  }
}

Over MCP the same answers arrive as tool errors, with the hint naming list_models.

Audit log

Every call and tool call is listed in Settings, API, Activity, as automation.list, automation.read, automation.runs, automation.create, automation.update, automation.pause, automation.resume, automation.run or automation.delete, with the automation's name and, for a run, its chat. See Audit log.

What stays in the app

Some changes need the app, where they can be shown and confirmed:

• Webhook triggers. Creating one, and its token, which the app shows once. A webhook automation can be read, changed in other ways, paused, run and deleted over the API; see Webhook trigger.
• The action type. An automation that runs a prompt stays a prompt, and one that runs a workflow graph stays a graph.
• Workflow graphs. Their nodes and routing are edited in Workflow Graphs. Over the API a graph automation shows its workflow_graph_id.

Turn it off

Settings, API, Automations has the switch Automations over the API and MCP, on by default.

• Off: no key or assistant sees or changes your automations. API calls answer 403 automations_disabled, the MCP tools are gone, and assistants are no longer offered the automations access when they connect. Your automations themselves keep running, and their cards no longer show Model cannot run.
• On again: keys and assistants that hold the scopes work again at once. When n8v has turned automations over the API off for everyone, the switch cannot turn them back on, and says so.

Questions

My assistant does not show the automation tools. It was connected before this release, or connected while the switch was off. Connect it again from the assistant. Settings, API, AI assistants names each app that lacks the access.

Why does an automation with a refused model still run? n8v lets the model run; the provider refused the last run. It may serve the model again, so n8v warns rather than blocks. Change the model to fix it.

Can a key create an automation that runs on a repository it may not use? No. Creating or moving one there answers 403 repo_not_allowed, and the key never sees automations there.

Does deleting an automation delete its chats? No. The chats it started stay in your task list.