Create or update snapshot schedule for an instance

put/instances/{id}/snapshot-schedule

Scheduled runs automatically choose snapshot behavior from current instance state:

Running or Standby source: create a Standby snapshot.
Stopped source: create a Stopped snapshot. For running instances, this includes a brief pause/resume cycle during each capture. The minimum supported interval is 1m, but larger intervals are recommended for heavier or latency-sensitive workloads. Updating only retention, metadata, or name_prefix preserves the next scheduled run; changing interval establishes a new cadence.

Path ParametersExpand Collapse

id: string

Body ParametersExpand Collapse

interval: string

Snapshot interval (Go duration format, minimum 1m).

retention: SnapshotScheduleRetention { max_age, max_count }

At least one of max_count or max_age must be provided.

max_age: optional string

Delete scheduled snapshots older than this duration (Go duration format).

max_count: optional number

Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).

minimum0

metadata: optional map[string]

User-defined key-value tags.

name_prefix: optional string

Optional prefix for auto-generated scheduled snapshot names (max 47 chars).

maxLength47

ReturnsExpand Collapse

SnapshotSchedule = object { created_at, instance_id, interval, 8 more }

created_at: string

Schedule creation timestamp.

formatdate-time

instance_id: string

Source instance ID.

interval: string

Snapshot interval (Go duration format).

next_run_at: string

Next scheduled run time.

formatdate-time

retention: SnapshotScheduleRetention { max_age, max_count }

Automatic cleanup policy for scheduled snapshots.

max_age: optional string

Delete scheduled snapshots older than this duration (Go duration format).

max_count: optional number

Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).

minimum0

updated_at: string

Schedule update timestamp.

formatdate-time

last_error: optional string

Last schedule run error, if any.

last_run_at: optional string

Last schedule execution time.

formatdate-time

last_snapshot_id: optional string

Snapshot ID produced by the last successful run.

metadata: optional map[string]

User-defined key-value tags.

name_prefix: optional string

Optional prefix used for generated scheduled snapshot names.

Create or update snapshot schedule for an instance

curl http://localhost:8080/instances/$ID/snapshot-schedule \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HYPEMAN_API_KEY" \
    -d '{
          "interval": "24h",
          "retention": {},
          "metadata": {
            "team": "backend",
            "env": "staging"
          },
          "name_prefix": "nightly"
        }'

{
  "created_at": "2026-03-09T01:00:00Z",
  "instance_id": "qilviffnqzck2jrim1x6s2b1",
  "interval": "24h",
  "next_run_at": "2026-03-10T02:00:00Z",
  "retention": {
    "max_age": "168h",
    "max_count": 7
  },
  "updated_at": "2026-03-09T01:30:00Z",
  "last_error": "invalid state transition: stopped snapshot requires source in Stopped, got Running",
  "last_run_at": "2026-03-09T02:00:00Z",
  "last_snapshot_id": "q7z1w7l2af4l8y7q1h7g2m3s",
  "metadata": {
    "team": "backend",
    "env": "staging"
  },
  "name_prefix": "nightly"
}

Returns Examples

{
  "created_at": "2026-03-09T01:00:00Z",
  "instance_id": "qilviffnqzck2jrim1x6s2b1",
  "interval": "24h",
  "next_run_at": "2026-03-10T02:00:00Z",
  "retention": {
    "max_age": "168h",
    "max_count": 7
  },
  "updated_at": "2026-03-09T01:30:00Z",
  "last_error": "invalid state transition: stopped snapshot requires source in Stopped, got Running",
  "last_run_at": "2026-03-09T02:00:00Z",
  "last_snapshot_id": "q7z1w7l2af4l8y7q1h7g2m3s",
  "metadata": {
    "team": "backend",
    "env": "staging"
  },
  "name_prefix": "nightly"
}