DELETE /v1/automations/{id} — remove a schedule and its run history

This is the second of the two destructive endpoints in the API, and like the first it is small, quiet and permanent. It takes an id, removes the automation, and returns two fields.

What goes

Three things at once, and only one of them is obvious.

The definition goes, which includes the instruction — usually the part that took the longest to get right, and the part nobody has a copy of anywhere else. The schedule goes, so nothing fires again. And the run history goes, which means the record of what this automation produced over however many months is no longer there to look at.

The documented order of operations exists because of that third one: read the automation before you delete it. That read is free, it returns the instruction verbatim, and it is the difference between a deletion you can recover from and one you cannot.

Deletion is not pausing

The most common reason people reach for this endpoint is not the reason it exists. "Stop sending me this for a while" is a pause, and an automation whose status is paused keeps its definition, keeps its history, and fires nothing at all. When you want it back you switch it on and the series continues.

Deleting to achieve the same effect works exactly once, and costs you the history and the instruction. If there is any chance the job comes back, pause it.

It is silent

Nothing announces that a schedule has gone. No inbox row appears, no alert fires, and the automation is simply absent from the listing afterwards. That is correct — the deletion was an instruction, not a fault — but it means a weekly report can stop arriving and the only visible symptom is that nobody received an email.

If several people depend on an automation, the reasonable habit is to tell them before removing it rather than after they notice.

Cleaning up safely

For a workspace that has accumulated automations over a year, the safe sequence is mechanical. List them. For each candidate, read it and keep the instruction somewhere durable. Check the latest run: an automation that has never run, or whose newest run is months old and failed, is a genuine candidate. Anything you are unsure about gets paused rather than deleted, and you revisit the paused set a month later when nobody has complained.

That last step is the one worth insisting on, because the cost of a paused automation is nothing and the cost of a wrong deletion is an instruction somebody has to reconstruct from memory.

The credential question

This endpoint needs write access, and so does its MCP equivalent. An assistant connected with the read-and-write scope can delete automations, which is the documented reason to treat such a connection as a workspace credential rather than a read token. Where a caller only needs to see what is scheduled, a read-only key does the whole job and cannot do this one.

Its twin on the other surface

The delete_automation MCP tool takes the same id, is equally destructive, and carries the same instruction to confirm with a read first. Between it and remove_prompt they are the only two tools on that surface that permanently remove anything.

Before you press it

A short checklist prevents nearly every regret associated with this endpoint. Read the automation and copy the instruction somewhere durable. Check who receives or depends on its output. Confirm the id you are about to send matches the name you mean, since ids are short and similar. And ask whether pausing achieves what you actually want, because in most cases it does. None of those steps costs anything, all of them are read-only, and together they take less time than reconstructing an instruction that took an afternoon to phrase correctly the first time.