# Operations & runs

> Plugs are operations, runs are their executions, routines put them on a schedule.

Backups, data syncs, and restarts are objects in the platform, not support tickets. Three of them matter here: plugs, runs, and routines.

## Plugs

A **plug** is an operation available on an instance: *back up the database*, *sync production data into staging*, *restart the app*. Each plug declares what parameters it takes and whether it is dangerous, supports a dry run, produces artifacts, or can be scheduled. The dashboard's **Actions** tab and the API expose the same list.

## Runs

Triggering a plug creates a **run**:

- **Steps** — what happened, in order, with timestamps.
- **A result** — success or failure, with the operation's output.
- **Artifacts** — files produced (a database dump, an export), downloadable through short-lived URLs.

Runs are asynchronous. Triggering returns a run id with `202` immediately; poll the run for its outcome.

## Routines

A **routine** is a named, saved operation on one instance: a `workflow` (each stock workflow runs one plug), its parameters, and a cadence — `on_demand`, `hourly`, `daily`, `weekly`, `monthly`, or `custom` (a cron expression, UTC). An instance can have several routines on the same plug, such as a nightly backup and an hourly one. A routine that repeats a plug needing confirmation (restore, redeploy) must be created with `acknowledge: true`; the acknowledgement is recorded against the calling token.

The platform pauses a routine it cannot run safely, for example when its plug is switched off. `paused_reason` says why; resuming clears it. Your own `enabled` switch is separate.

## Over the API

Plugs and runs:

- `GET /api/v1/instances/{slug}/plugs` — what an instance can do (`read_plugs` scope).
- `POST /api/v1/instances/{slug}/plugs/{plug}/runs` — trigger a plug (`write_plugs`). Returns `202` with `data.run_id`.
- `GET /api/v1/runs`, `GET /api/v1/runs/{id}` — run history and detail (`read_plugs`).
- `GET /api/v1/runs/{id}/artifacts/download` — a short-lived download URL for an artifact (`read_plugs`).

Routines:

- `GET /api/v1/routines`, `GET /api/v1/routines/{id}` — list and read (`read_plugs`).
- `POST /api/v1/routines`, `PATCH /api/v1/routines/{id}`, `DELETE /api/v1/routines/{id}` — create, update, delete (`write_plugs`).
- `POST /api/v1/routines/{id}/runs` — run a routine now (`write_plugs`).
- `POST /api/v1/routines/{id}/resume` — clear a system pause (`write_plugs`).

The same operations are available to AI agents through the [MCP server](/api/mcp), under the same scopes.