Snapshots API

All endpoints need a bearer token:

http

Authorization: Bearer <jwt-or-apikey>

A snapshot is an on-pod, point-in-time image of a pod that restores in place. If you want a copy that restores as a separate new pod, you want backups instead. The difference is explained in Snapshots vs backups.

The snapshot object

json

{
  "id": "6a4d5b83b7006ccae6391d55",
  "name": "snap-1757980800-k3n8qa",
  "podId": "6a4d5b83b7006ccae6391810",
  "accountId": "6a4d5b83b7006ccae639100a",
  "type": "manual",
  "status": "completed",
  "createdAt": "2026-09-16T03:00:00Z",
  "updatedAt": "2026-09-16T03:00:42Z"
}

Field	Meaning
`name`	Generated, not yours to choose. Manual snapshots are named `snap-<timestamp>-<suffix>`, scheduled ones `auto-<timestamp>-<suffix>`.
`type`	`manual` or `auto`.
`status`	`pending`, `completed`, or `failed`.
`error`	Only present on a `failed` snapshot, with the reason.

List snapshots for a pod

http

GET /api/pods/:id/snapshots

Needs snapshots:read. Returns a plain array of that pod's snapshots, manual and auto together, in no guaranteed order - sort on createdAt if order matters.

bash

curl https://cloud-api.microapps.io/api/pods/6a4d5b83b7006ccae6391810/snapshots \
  -H "Authorization: Bearer $MICROAPPS_API_KEY"

json

[
  {
    "id": "6a4d5b83b7006ccae6391d55",
    "name": "snap-1757980800-k3n8qa",
    "podId": "6a4d5b83b7006ccae6391810",
    "accountId": "6a4d5b83b7006ccae639100a",
    "type": "manual",
    "status": "completed",
    "createdAt": "2026-09-16T03:00:00Z",
    "updatedAt": "2026-09-16T03:00:42Z"
  },
  {
    "id": "6a4d5b83b7006ccae6391d61",
    "name": "auto-1757894400-p7w2ce",
    "podId": "6a4d5b83b7006ccae6391810",
    "accountId": "6a4d5b83b7006ccae639100a",
    "type": "auto",
    "status": "completed",
    "createdAt": "2026-09-15T03:00:00Z",
    "updatedAt": "2026-09-15T03:00:39Z"
  }
]

Create a manual snapshot

http

POST /api/pods/:id/snapshots

Needs snapshots:create and at least $3 of account credit (402 otherwise). No body. Response 202 with the new snapshot in pending - it finishes in the background.

bash

curl -X POST https://cloud-api.microapps.io/api/pods/6a4d5b83b7006ccae6391810/snapshots \
  -H "Authorization: Bearer $MICROAPPS_API_KEY"

json

{
  "id": "6a4d5b83b7006ccae6391d55",
  "name": "snap-1757980800-k3n8qa",
  "podId": "6a4d5b83b7006ccae6391810",
  "accountId": "6a4d5b83b7006ccae639100a",
  "type": "manual",
  "status": "pending",
  "createdAt": "2026-09-16T03:00:00Z",
  "updatedAt": null
}

You can keep 4 manual snapshots per pod - the fifth slot is always held back for the auto schedule. At the limit you get 400 "Snapshot limit reached. Maximum 4 manual snapshots per pod (1 slot reserved for automatic snapshots)", so delete one first. Failed snapshots do not occupy a slot. The same number is on GET /api/user/account as maxSnapshotsPerPod if you would rather read it than hardcode it.

Restore from a snapshot

http

POST /api/pods/:id/snapshots/:snapId/restore

Needs snapshots:update. No body. Response 202:

json

{ "message": "Snapshot restore started" }

bash

curl -X POST https://cloud-api.microapps.io/api/pods/6a4d5b83b7006ccae6391810/snapshots/6a4d5b83b7006ccae6391d55/restore \
  -H "Authorization: Bearer $MICROAPPS_API_KEY"

The pod rolls back in place and moves through Restoring while it happens. Two rules:

The pod must be Running or Stopped, otherwise 400 "Pod must be running or stopped to restore a snapshot". (No need to stop it yourself first - restore does that.)
The snapshot must be completed, otherwise 400 "Only completed snapshots can be restored".

When the restore finishes, the pod is left Stopped - start it again when you're ready.

Restoring is destructive

Anything written after the snapshot was taken is gone. Want to keep the current state too? Take a manual snapshot first, then restore.

Delete a snapshot

http

DELETE /api/pods/:id/snapshots/:snapId

Needs snapshots:delete. Response 200:

json

{ "message": "Snapshot deleted" }

Immediate and irreversible.

Set the auto snapshot schedule

http

PUT /api/pods/:id/snapshot-schedule

Needs snapshots:update.

json

{ "schedule": "daily" }

schedule is one of:

Value	Meaning
`""`	Disabled - no automatic snapshots.
`"daily"`	Every day at 3:00 AM UTC.
`"weekly"`	Every Sunday at 3:00 AM UTC.
`"monthly"`	The 1st of every month at 3:00 AM UTC.

Anything else is 400 "Invalid schedule: <value>".

bash

curl -X PUT https://cloud-api.microapps.io/api/pods/6a4d5b83b7006ccae6391810/snapshot-schedule \
  -H "Authorization: Bearer $MICROAPPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"daily"}'

Response 200:

json

{ "message": "Snapshot schedule updated" }

The setting shows up as snapshotSchedule on the pod object, and the field is omitted entirely once you disable it.

One slot is held back for the schedule, so a full set of manual snapshots never blocks it. Automatic snapshots rotate among themselves and fill whatever the manual ones are not using: four manual snapshots leave room for one automatic one, none leaves room for five. Your manual snapshots are never touched by the schedule.

Snapshots API ​

The snapshot object ​

List snapshots for a pod ​

Create a manual snapshot ​

Restore from a snapshot ​

Delete a snapshot ​

Set the auto snapshot schedule ​

See also ​

Snapshots API

The snapshot object

List snapshots for a pod

Create a manual snapshot

Restore from a snapshot

Delete a snapshot

Set the auto snapshot schedule

See also