Start computer
Boot a stopped computer, optionally for a set number of hours.
frozen or stopped. A frozen computer’s archived disk is restored, including files, installed software, and configuration, and it cold-boots on a host chosen for it. A stopped computer whose virtual machine is still on its host is booted there from its own disk instead. A suspended computer that was moved off its host to storage is woken with its memory intact, in about a minute.
instance_id, and it can land on a different host with a different address and ports. Orgo asks for the previous ports and VNC password back, but does not guarantee them. Re-fetch GET /computers/{id} afterwards. Only the disk is restored: processes and other in-memory state from before the stop are gone. The call can take considerably longer than a normal request while the saved disk is fetched and the computer boots.Path parameters
instance_id. Both resolve to the same computer. A frozen computer, or one asleep in storage, has no instance_id, so address it by UUID.Query parameters
true or false. true returns 202 immediately instead of waiting, as described in Return immediately and poll. Any other value returns 400.Body parameters
The body is optional. When you send one, it must be a JSON object.1 to 720 (30 days). The hours count from when the computer is running, not from the request. null takes any end off. Send ends_in_hours or ends_at, not both. Omitted, the Start sets no end, as described in Start for a set number of hours.null takes any end off."delete", sent with ends_in_hours or ends_at, is accepted and changes nothing. Sent without either it returns 400 with code INVALID_ENDS: on_end goes with ends_at or ends_in_hours. Without an end it changes nothing. A Start never touches the end a computer already has. Any other value, "stop" included, returns 400 with code INVALID_ENDS: A computer with an end is deleted when its time is up. To keep a computer, leave out the end. Nothing starts."hourly" is read. It moves a frozen computer that the workspace owner’s plan no longer funds, such as an older computer on a Free account, to running by the hour from your credit, then starts it. Only the workspace owner can send it, signed in or with an account-wide key that has full access or Billing write. Your credit must cover an hour of this computer and an hour of your other hourly computers. For a computer that cannot move, it changes nothing.Response
true only when the computer’s record said stopped but the computer was still running on its host, so the record was corrected instead of a second copy being booted. No boot happened.true only when a stopped computer was booted on its existing host from its own disk, rather than restored from its archive.ends_in_hours or ends_at.
"delete" once an end is set, since the computer is deleted then, or null with no end. With end_not_set, the computer’s current value, which is "stop" for an end set before every end deleted the computer.ends_at once an end is set, or null with no end. With end_not_set, the computer’s current value.null when its time is not prepaid.prepaid_until. What is held from your credits for the run, in cents. null when prepaid_until is.error (why, in words) and code, beside the end the computer has. The start itself succeeded. The codes are listed in When the end is not set.running computer: it returns { "success": true } and changes nothing, except that an end you send is set. Only frozen and stopped computers, and suspended computers in storage, are startable. A suspended computer still on its host, and every other status, returns 409. Use Resume for one on its host.
Example
Response
Start for 4 hours
success and the end fields. Nothing is prepaid.
Start for a set number of hours
Sendends_in_hours or ends_at to give the computer an end as it starts. When the end is up Orgo deletes the computer, running or stopped, with everything on it, as described in Computers with an end. To keep a computer, send no end.
- The end is checked before anything starts, by the rules Update computer uses. A bad one returns
400,403, or503, listed in Errors, and nothing starts. - The end is set once the computer is running, the way Update computer sets it. A Start that fails sets no end and holds no credit.
- A computer stopped when an earlier end ran out (
on_end: "stop", an end set before every end deleted the computer) comes back with the new end, or with none when the Start sends none. A computer stopped before its end keeps that end when you start it without one. nulltakes any end off, on any computer.- A computer that runs by the hour is billed by the hour, with no prepay, after a Start that sets no end, even when it still has an end ahead. A Start that sets an end prepays the run to it once the computer is running. Only the workspace owner prepays, and on a paid plan only signed in or with a key that has full access or Billing write, as described in Who can prepay. When the credit is short or you may not prepay, the end is still set, the time is billed by the hour, and the answer carries
prepay_warning. - A key for one computer can start the computer but cannot set its end: a body that names an end returns
403with codecomputer_scope, and nothing starts. A computer’s own key and its identity token cannot start a computer at all:403with codecomputer_key.
When the end is not set
An end that could not be set never fails the Start. The200 carries end_not_set, beside the end the computer has:
error starts with Started, but no end was set.
Errors
operation_id and poll_url in its body.
A 402 for credit or the plan, a 402 with no code, HOURLY_NEEDS_BILLING, and FREE_HOURLY_BUSY also carry retryable (whether the same request can work later as it is), docs_url, and next, the call that fixes it, as { "method", "url", "why" } with a body when the call needs one. With hourly_available: true, next is this Start with { "billing_mode": "hourly" }. When next adds credit, the body also has add_credit_url, the page where a person adds it, and with a Bearer credential error ends with the call, such as Next: POST /api/credits/checkout.
Return immediately and poll
Send?async=true, a JSON body { "async": true }, or the header Prefer: respond-async to return 202 immediately. The response includes id (the computer UUID), status (starting or stopping), operation_id, operation, and poll_url, plus Location and Retry-After: 2 headers. A Start that sends an end also carries end_pending, the end you asked for, such as { "ends_in_hours": 4 }. Once the computer is running, the operation’s result carries the end fields described in Response. Repeating the same action while it is pending returns the same operation. An opposite action returns 409 with code OPERATION_IN_PROGRESS.
Fetch poll_url with the same authentication until the operation reports succeeded, failed, or needs_review. A needs_review result means the host’s outcome is uncertain. Orgo checks the computer and settles the operation on its own; until then, a new start or stop returns 409 with code OPERATION_NEEDS_REVIEW. See Get computer operation.
Without the async option the request waits for completion, up to 300 seconds. If still pending, it returns 202 and the same polling fields. Both modes preserve disk data; stopping discards live processes and memory, and starting cold-boots with potentially different connection details.Authorizations
Headers
Query Parameters
Body
Not a choice: a computer with an end is deleted when its time is up, running or not, with everything on it. "delete", sent with ends_in_hours or ends_at, is accepted and changes nothing. Without either it returns 400 (INVALID_ENDS): on_end goes with ends_at or ends_in_hours. Without an end it changes nothing. Any other value, "stop" included, returns 400 (INVALID_ENDS): A computer with an end is deleted when its time is up. To keep a computer, leave out the end.
delete, null Only "hourly" is read. It moves a frozen computer that the workspace owner's plan no longer funds, such as an older computer on a Free account, to running by the hour from your credit, then starts it. Only the workspace owner can send it, signed in or with an account-wide key that has full access or Billing write. Your credit must cover an hour of this computer and an hour of your other hourly computers. For a computer that cannot move, it changes nothing.
hourly Response
Started, or already running
Present when the body sent an end. What happens at the end, read only: "delete" (deleted at ends_at, as every end set now is), "stop" (an end set before every end deleted the computer: stopped at ends_at, deleted 7 days later unless it is started), or null with no end.
delete, stop, null Present when the end was set but its time was not prepaid: The new time is billed by the hour. Only the account owner can prepay it, signed in or with a key that has Billing write. when you may not prepay, or The new end is set, and the time to it is billed by the hour: your credit does not cover prepaying all of it. when the credit is short.
Present when the end you asked for was not set. The start or resume itself succeeded. code is INVALID_ENDS (an ends_at that passed meanwhile), COMPUTER_BUSY, insufficient_credit (a later end than a running prepay that the credit cannot cover, with needed_cents, available_cents, and keep_cents when there is any), ENDS_UNAVAILABLE, NOT_FOUND, END_NOT_SET, or, on a resume still under way, STILL_RESUMING.