Suspend the workspace if it stays idle for after_seconds from now (e.g. at the end of an agent turn)
Records a deferred suspend for the cell’s idle loop: once the workspace has been idle for after_seconds (0..3600; 0 = as soon as it is idle), it is suspended (within a few seconds of activity flush grace), at not_before (= now + after_seconds) at the earliest. A tool call after the request (the next turn) or a resume cancels it for good. Other work only defers it: a command still running, an attached exec/PTY stream or a keepalive postpones the suspend until after_seconds after it ends. It applies under every idle policy (never included) and only ever shortens the policy’s wait; a policy that suspends sooner still does. Repeating replaces the pending request (the new requested_at counts); DELETE cancels it; idle.suspend_request on the workspace shows it. 202 {workspace, operation: null, suspend_request}; when a suspend is already in progress, 202 {workspace, operation: that suspend, suspend_request: null} and nothing is recorded. The suspend, when it happens, is a system suspend operation with input.reason requested_after_idle (input.requested_at, input.after_seconds). Errors: 409 session_lifetime, workspace_deleted, operation_in_progress (another lifecycle operation is active), not_running, not_supported_for_mode (file-first). Supports Idempotency-Key.
Request
- Base URL: https://api.shardflux.dev
- URL: https://api.shardflux.dev/v1/workspaces/{workspace_id}/suspend-when-idle
- Auth: HTTP bearer
Path parameters
UUIDv7, lowercase canonical form.
Request body
Response
suspend_request: the recorded request. operation: set (and suspend_request null) only when a suspend was already in progress.
Changes
No recorded changes to this operation across all 1 revision of this API.