Take a snapshot

Captures the disk. Pass memory: true to capture the running session with it, so a restore comes back to a live desktop rather than to a boot.

THE CAPTURE OUTLIVES THIS CALL. You get a 202 and a row in state: "capturing" the moment the capture is accepted, not when it finishes — copying a disk takes minutes and scales with how much has been written to it, which is longer than any HTTP request survives. Poll GET /snapshots for the id you were given and wait for the row to STOP READING capturing.

MANUAL CAPTURES COUNT STORED BYTES AND CAPTURES ALREADY IN PROGRESS across the account. A capture can start while usage is below the allowance even if its eventual size crosses it; later captures are refused with 402 until usage is back under the allowance. A capture requested while another manual capture on the account is still being admitted answers 503 — retry. If acceptance cannot be confirmed, check the snapshot list before retrying. Admission also answers 503 (“Snapshot admission could not be confirmed…”) whenever any host in the fleet cannot confirm what snapshots it holds — one that is down or not answering, one whose snapshot storage is failing, or one running software too old to confirm it — even a host that holds nothing of yours; it lasts as long as that host’s state does. Automatic (scheduled) captures count toward the allowance too, so they can be what brings an account to the 402 — and a scheduled capture can be skipped, rather than taken, when the allowance is full, or on a new account or a computer newly placed on its host until the next complete hourly measurement of the allowance reaches that host. See PUT /computers/{id}/schedule.

WAIT FOR “no longer capturing”, NOT FOR pending SPECIFICALLY. pending is where a finished capture lands, but replication to backup storage can complete between two of your polls and carry it straight on to durable — a loop waiting for the literal string pending can watch a small snapshot go past and never match. Both are states you can restore, clone and delete from.

ONE CAPTURE OF A COMPUTER AT A TIME, AND IT LASTS UNTIL THE UPLOAD. A capture holds its computer until its upload to backup storage has finished, which is later than when it stops reading capturing. Another capture of the SAME computer in that window — yours, or a scheduled one — is refused with 409 and reason: "contention"; retry, and it is accepted once the upload has finished, which is ordinarily when the previous row reads durable. Captures of other computers are not held up by it.

THE ID YOU ARE GIVEN IS THE SNAPSHOT’S OWN. It does not change when the capture lands, so it is what you poll on — never "the newest snapshot of this computer", which a scheduled capture finishing in the same window gets wrong.

EVERYTHING THAT CAN REFUSE A CAPTURE IS REFUSED HERE, before the 202: no such computer (404), a disk still being copied (409), a computer being deleted (409), one that has not yet finished taking on an identity of its own, such as a new computer that has never been started (400; start it, let it come up, and try again), a host with no snapshot storage configured (400), a capture of this computer still holding it (409, reason: "contention"; see above), a memory snapshot of a computer that is not running (409, reason: "unavailable"; start it), an allowance that will not stretch (402), a computer the platform is holding for disk-space recovery after a suspend or memory snapshot failed (503, “waiting for disk-space recovery”; wait, or stop it to discard the paused session), and three that only a memory snapshot of a computer holding secrets meets: its secrets still being delivered (409, reason: "contention", and worth retrying — it clears in a moment; reason: "unsupported" instead for a session they were never delivered to and that nothing is delivering to now, which a stop and a start clears; for such a session, reason: "contention" when its host could not read whether it is running just now, worth sending again shortly, and reason: "unsupported" when its host cannot read its process until support repairs the host), a session that may still hold secret values it is no longer bound to (409 until the computer restarts), and a host that does not seal saved memory (409; a disk snapshot is the way out). A 202 means the capture started, not that it will land: a capture waits its turn behind others on the same host, and when that turn comes a memory capture checks again that the computer is running and the three secrets refusals above, and, on a computer holding secrets, that its guest says its secrets reached the boot it is running and that it does not reboot during the capture. So one already accepted can still end if the computer stops, a delivery starts or its bindings change while it waits, and on such a computer if it reboots or its guest does not answer. Any capture can also end after the 202 when the host does not have enough unreserved disk space for the copy, and a memory capture that fails while the host is low on disk space can leave the computer paused, still reading running (see status on Computer). A capture that then fails leaves no snapshot and no row — the capturing row disappears and nothing takes its place, which is how you tell that from one still running.

Requires the member role or higher.