Operations & runs

Backups, data syncs, and volume snapshots 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, snapshot the data volumes. 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, a volume archive), downloadable through short-lived URLs. See Backups & restore.

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. Cadences are on_demand, hourly, daily, weekly, monthly, and 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 recurring routine whose plug is marked schedule_tier: "confirmed" must be created with acknowledge: true; the acknowledgement is recorded against the calling token. An on_demand routine needs none, since nothing repeats it.

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 /runs/{id} also accepts write_instances for the runs that scope's own writes return (an instance's apply, redeploy or teardown), so a provisioning token can poll them; any other run answers 403 insufficient_scope to it.
• GET /api/v1/runs/{id}/artifacts/download?key=…: a short-lived download URL for one artifact the run recorded; key comes from the run detail (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).

Most of these operations are available to AI agents through the MCP server, under the same scopes. See the tool list there.