Snapshot Before Deploy

Role: Pipeline · API: POST /api/v1/snapshots then GET /api/v1/executions/{id}

Prefer the quemsi CLI: it posts the snapshot and waits. Curl below is the same contract. For clicks in the console, use Snapshot before a schema change. For a laptop coding agent, use Coding agent snapshot.

Before you start

A token with snapshot and read scopes. See Create API tokens.
You know the data name and agent name. The agent must be ONLINE.
If that data has more than one forward (backup) flow on the agent, you must pass flow (the flow name). One flow: omit flow.
Pick tags you can restore later, for example release=1.42.0 and purpose=pre-deploy. Do not reuse a nightly tag if you need this snapshot as its own Restore card.

Steps

1

Snapshot with the CLI

--wait is the default. Do not start the migration or deploy until this command exits 0.

quemsi snapshot --data shopping-cart --agent ci-staging \
  --tag release=1.42.0 --tag purpose=pre-deploy \
  --descript "pre-deploy snapshot"

2

Or POST the snapshot with curl

RESPONSE=$(curl -sS -X POST "$QUEMSI_URL/api/v1/snapshots" \
  -H "Authorization: Bearer $QUEMSI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "shopping-cart",
    "agent": "ci-staging",
    "tags": { "release": "1.42.0", "purpose": "pre-deploy" },
    "descript": "pre-deploy snapshot"
  }')
EXECUTION_ID=$(printf '%s' "$RESPONSE" | jq -r .id)

3

Poll until terminal (curl only)

Do not start the migration or deploy while status is SCHEDULED or RUNNING.

while true; do
  STATUS=$(curl -sS "$QUEMSI_URL/api/v1/executions/$EXECUTION_ID" \
    -H "Authorization: Bearer $QUEMSI_TOKEN" | jq -r .status)
  case "$STATUS" in
    SUCCESS) break ;;
    FAILED|SKIPPED) echo "snapshot $STATUS"; exit 1 ;;
  esac
  sleep 2
done

4

Deploy, and restore only if you need to

Run the schema change or release. If you need the previous state, restore with the same tags (or the versionId from the snapshot’s execution). Restore overwrites the target database — see Restore before tests for the poll loop.

If snapshot fails

ambiguous-flow — pass flow with the forward flow name.
no-forward-flow — that data has no backup flow on this agent. Create one in the UI first.
Agent offline or token bound to another agent — same checks as restore.

Not this page

Clicks on Take Snapshot — Take a tagged snapshot.
Laptop coding agent before a local schema change — Coding agent snapshot.
Scheduled nightly backups — Schedule a recurring backup (timers in the UI, not this API).