Suspend a computer
Saves the running session to disk and gives the host its memory back, without ending the session. Starting it again resumes the desktop exactly where it was. The guest’s clock is set to the current time within a few seconds of the resume, through its guest agent — best effort, so a guest whose agent does not answer keeps the time it was suspended at until NTP corrects it — and the desktop panel’s clock can show the old time for up to a minute after that. A stopped computer answers 409 with reason: "unavailable": start it before suspending a session.
A computer that holds secrets suspends only on a host that seals saved sessions: its memory is encrypted on its way to disk. Elsewhere, and while its secrets are still being delivered, it answers 409: with reason: "contention" while a delivery is on its way, which passes in a moment; with reason: "unsupported" for a session its secrets were never delivered to and that nothing is delivering to now, which only a stop and a start clears; and with no reason when its guest did not say whether its secrets reached the boot it is running. For a session its secrets were never delivered to, it also answers 409 with reason: "contention" when its host could not read whether it is running just now (send it again shortly), and with reason: "unsupported" when its host cannot read its process until support repairs the host. One whose bindings dropped a secret or moved one to another revision while it ran cannot be suspended until it restarts, because its memory may still hold the old value.
A refusal known to occur before this suspend attempt starts saving includes suspend_outcome: "not_started". Without this field, a failed request may have saved a session: refresh status before further lifecycle actions. HTTP 400 or 409 alone does not establish whether saving began.
A suspend that fails, especially while the host is low on disk space, can leave the computer paused, still reading running. If start, restart, suspend or snapshot then answer 503 (“waiting for disk-space recovery”), the platform is holding it for recovery: it resumes by itself once that recovery can finish, or stop it to discard the paused session. A failure saying “this computer remains paused because the host is low on disk space” is always held that way, and so can other failures be, at any free space. A suspend sent again that is not refused that way goes ahead, and it completes a session that was saved but could not be recorded rather than saving a second one.
Requires the member role or higher.
Request
- Base URL: https://app.mandala.computer/api/v1
- URL: https://app.mandala.computer/api/v1/computers/{id}/suspend
- Auth: HTTP bearer
Path parameters
The computer 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
Suspended.
Changes
No recorded changes to this operation across all 1 revision of this API.