Restore a snapshot
Puts this snapshot back onto the computer it came from, replacing its current disk. Needs that computer to still exist — an orphaned snapshot cannot be restored, only cloned.
A snapshot held by two hosts at once — a move part way through handing its history over — is served from the copy on the host its computer now lives on. One that cannot be attributed that way, such as an orphan, answers 409 until the handover finishes; nothing is changed.
A snapshot taken before its computer moved to another host (POST /computers/{id}/move) is carried to the new host after the move. Until it lands, restoring it answers 409 with reason: "contention", saying it is still being carried over; try again in a few minutes. If the carry failed, the 409, with no reason, says it is still on the host the computer moved from, and that does not clear on its own: clone it instead, or ask support to move it. Nothing is changed either way. Cloning the snapshot works while it is being carried, except while the new host is taking it over, when a clone can answer 409 as well; retry once the carry has finished.
IT LEAVES THE COMPUTER RUNNING, whatever state it was in. A restore of a stopped computer boots it, and that is a start like any other: charged, and refusable by your plan. A disk snapshot comes back to a fresh boot; a memory one resumes the captured session. Either way any suspended session the computer was holding is discarded, since it was saved against the disk being replaced. On a host without enough free disk space for it, a restore answers 503 before anything is touched. If space runs short after the disk has been replaced, the start at the end can still be refused with 503 (“this host is low on disk space…”), and the computer is left stopped on the restored disk: start it once space there has been freed. If that message adds that its paused QEMU could not be stopped, stop the computer before trying again.
A computer that holds secrets restored from a DISK snapshot gets them delivered afresh at that boot, with their current values, exactly as a start delivers them; the snapshot never carried them. This delivery has the same workspace-conflict refusals and recovery as POST /computers/{id}/start. One restored from a memory snapshot resumes holding what it held when the snapshot was taken. A memory snapshot taken without sealing is refused onto a computer that now holds secrets (409, reason: "unsupported"), and a sealed one with 400 and no reason when the platform will not open its saved memory for this computer, for example because a secret it held has since been deleted or moved out of the computer’s scope. Both are checked before anything is stopped, and then nothing is stopped or replaced. The saved memory is opened again when it loads, so a refusal that arrives only then — a secret deleted in the meantime, say — ends the restore after the disk has been replaced, leaving the computer stopped.
A MEMORY SNAPSHOT ONLY LOADS INTO THE SHAPE IT CAME OFF. Resize the computer after capturing one and the restore is refused — the vCPU count and the memory size are part of a saved memory image, not decoration around it. The refusal names the shape to go back to; clone is the other way out: a clone resumes the session in a new computer at the captured shape — for a snapshot of a computer that held secrets only with inherit_secrets: true, and otherwise it is built from the disk and says so with memory_dropped: true — or, with memory: false, is built from the disk alone; one built from the disk lands stopped and boots fresh when you start it (see POST /snapshots/{id}/clone). Refused before anything is taken down, so a computer that gets this answer is untouched.
Requires the member role or higher.
Request
- Base URL: https://app.mandala.computer/api/v1
- URL: https://app.mandala.computer/api/v1/snapshots/{id}/restore
- Auth: HTTP bearer
Path parameters
The snapshot id.
Headers
Optional: a key of your choosing, 1 to 255 printable ASCII characters with no spaces (a UUID is ideal), that makes this call safe to send again after a lost answer. The call and its operation are recorded BEFORE it is carried out, so GET /operations?idempotency_key= finds it however the connection ended. For 24 hours, the same key with the byte-identical request (method, path, query and body, from a credential of the same scope) is not carried out again: it answers 409 idempotency_in_progress while the first is running, and the original answer — status and body, with Idempotent-Replayed: true — once it has finished. An answer too large to keep (over 1 MiB) is replayed instead as a 200 carrying {operation_id, operation}, also with Idempotent-Replayed: true: operation is the call’s operation, or null when there is none to show. Keys are kept per scope: a key used by a workspace's credential and the same key used by another workspace's, or by an account-wide one, are different keys, and neither is refused because of the other. A replayed body omits the desktop credentials the original carried (vnc, with its tokens and URLs): read the computer (GET /computers/{id}) for them. The same key on a different request is a 422 with code: "idempotency_key_reused", and a malformed key (empty, too long, outside printable ASCII, or the header sent twice) a 400 with code: "idempotency_key_invalid"; neither does anything. A call refused with a 4xx that did nothing releases its key, so it may be sent again under the same one. The exception is a delete whose 4xx says the computer was deleted — computer_deleted: true, or a purge result beside computer_deleted: false (it was deleted, then listed again): it happened, so its key keeps that answer and its operation is succeeded. Except a 409 with reason: "contention" whose purge deleted, queued and left in doubt nothing (the computer was already gone and copies in use refused the purge): nothing happened, so its key is released and the same request may be sent again under it. With computer_deleted: null, or false where the platform cannot confirm the computer was left in place, it is an unknown outcome: its key answers 409 idempotency_in_progress until the platform gives up on it, then 409 idempotency_outcome_unknown. A 5xx answer that names an operation_id is an unknown outcome too: that is the operation reserved for it. From then on the same key answers 409 idempotency_outcome_unknown, naming that operation (not idempotency_in_progress): read the computer, or the operation. The operation stays pending until the platform gives up on it; if it never learns how the call ended, it becomes failed with error.code: "lost". Some 5xx answers are refusals given before the call was sent anywhere — the platform could not check the account’s usage, or find a host for the call, for example — and some are a create or clone the host confirms it refused before building anything, such as a 503 from a host with no room left, and some are a start, restore or suspend the host confirms it refused before changing anything (a sealed session whose key could not be opened or whose transport failed first; on a suspend, suspend_outcome: "not_started"). Those name no operation_id: nothing was done, so the key is released as a 4xx refusal’s is, and the same call may be sent again under the same key. A host running older software cannot confirm such a refusal, so its 5xx is an unknown outcome like any other. A 5xx without an operation_id is not proof that nothing was done on its own: a call that records no operation (a PATCH that does not resize) names none, and neither does one whose operation could not be recorded. Sending the same call again under the same key is safe after any 5xx: it is carried out if its key was released, and answered 409 idempotency_outcome_unknown if not.
Response
Restored.
Changes
No recorded changes to this operation across all 1 revision of this API.