> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Stop computer
> Shut down a running computer.
Stops a running computer. Its disk is archived to object storage, so files, installed software, and configuration are all kept. Its host and IP are released, so a stopped computer costs no compute.
A successful stop leaves the computer in status `frozen`. That is the value [`GET /computers/{id}`](/api-reference/computers/get) reports afterwards, and the state [start](/api-reference/computers/start) restores from.
The archive is written and verified before the computer is torn down. If the response is lost or finalization fails, check the operation status: `needs_review` means the result must be reconciled before retrying. A stopped computer has no `instance_id` until it is started again, so address it by UUID. On [start](/api-reference/computers/start) it gets a new `instance_id` and can land on a different host with a different address and ports. Processes and other in-memory state are **not** preserved. Only the disk survives.
## Path parameters
Computer UUID or `instance_id`. Both resolve to the same computer.
## Query parameters
`true` or `false`. `true` returns `202` immediately instead of waiting, as described in [Return immediately and poll](#return-immediately-and-poll). Any other value returns `400`.
## Response
`true` when the computer was stopped, or was already `frozen`.
Stopping is idempotent only for a computer that is already `frozen`. Any other non-`running` status returns `409` rather than succeeding. That includes `stopped`, which Orgo records when a computer's virtual machine has stopped or is gone from its host.
Only Linux and Windows computers can be stopped. Any other operating system, or a physical device, returns `400` with code `STOP_UNSUPPORTED`.
## Example
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/stop \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import requests
response = requests.post(
f"https://www.orgo.ai/api/computers/{computer_id}/stop",
headers={"Authorization": f"Bearer {api_key}"}
)
if response.json().get("success"):
print("Computer stopped")
```
```javascript JavaScript theme={null}
const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/stop`, {
method: 'POST',
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { success } = await response.json();
if (success) console.log('Computer stopped');
```
### Response
```json theme={null}
{
"success": true
}
```
## Errors
| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "…", "code": "STOP_UNSUPPORTED" }` | The computer's operating system or hardware cannot be archived. `code` is `DEVICE_LIFECYCLE_UNSUPPORTED` for a device Orgo manages directly. |
| `400` | `{ "error": "Expected a JSON object with an optional boolean async field." }` | The body is not empty and is not a JSON object with an optional boolean `async`. |
| `400` | `{ "error": "async must be true or false" }` | The `async` query parameter is neither `true` nor `false`. |
| `401` | `{ "error": "Invalid API key" }` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{ "error": "Authentication required" }` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `402` | `{ "error": "Choose a plan to archive this computer.", "code": "TRIAL_ARCHIVE_UNAVAILABLE" }` | The computer is a trial computer. |
| `402` | `{ "error": "Choose a plan to continue." }` | The computer is a trial computer whose trial has ended. |
| `403` | `{ "error": "You do not have access to this workspace." }` | You are not a member of the computer's workspace. |
| `403` | `{ "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)." }` | You have view-only access to the workspace. |
| `403` | `{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }` | The API key is scoped to a different workspace. |
| `404` | `{ "error": "Desktop not found" }` | No computer matches the id. |
| `409` | `{ "error": "Computer is not running (status: stopped)", "code": "not_stoppable" }` | The computer is in any non-`running` status other than `frozen`. |
| `409` | `{ "error": "…", "code": "migrating" }` | The computer is being moved to another host. Retry in a few minutes. |
| `409` | `{ "error": "A different operation is already in progress.", "code": "OPERATION_IN_PROGRESS" }` | A start is still pending for this computer. |
| `409` | `{ "error": "The previous operation was interrupted and is being checked. Try again in a few minutes.", "code": "OPERATION_NEEDS_REVIEW" }` | An earlier start or stop is in `needs_review`. |
| `500` | `{ "error": "…", "code": "…" }` | The archive or teardown failed. Check the operation status before retrying; an uncertain result is fenced as `needs_review`. |
| `503` | `{ "error": "Computer not ready. VMM has not assigned a server yet", "code": "NOT_READY" }` | The computer has no host on record yet. |
| `503` | `{ "error": "…", "code": "frozen_disabled" }` | Archived-disk storage is not configured for this fleet. |
| `503` | `{ "error": "Service temporarily unavailable. …" }` | Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay. |
A failure that happens while the operation runs also carries `operation_id` and `poll_url` in its body. A host that refuses the archive answers with its own `4xx` status and `code`.
## 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. 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](/api-reference/computers/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.
## OpenAPI
````yaml POST /computers/{id}/stop
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
paths:
/computers/{id}/stop:
post:
tags:
- Computer Lifecycle
summary: Stop computer
description: >-
Stops a running computer. Its disk is archived and verified before the
computer is torn down, and its host is released. A successful stop
leaves the computer `frozen`. Stopping an already `frozen` computer
succeeds; any other non-`running` status returns `409`. Only Linux and
Windows computers can be stopped. Accepts the computer UUID or its
`instance_id`.
operationId: stopComputer
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
- name: async
in: query
required: false
description: >-
`true` returns `202` immediately instead of waiting. Omitted, the
request waits up to 300 seconds. Any value other than `true` or
`false` returns `400`.
schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
- name: Prefer
in: header
required: false
description: Send `respond-async` for the same effect as `?async=true`.
schema:
type: string
enum:
- respond-async
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
async:
type: boolean
default: false
description: >-
`true` returns `202` immediately. An empty body is accepted;
any body that is not a JSON object with an optional boolean
`async` returns `400`.
responses:
'200':
description: Stopped, or already `frozen`
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
example:
success: true
'202':
description: >-
Accepted. Returned immediately with `?async=true`, a body `{
"async": true }`, or `Prefer: respond-async`, and by a synchronous
request still pending after 300 seconds. Poll `poll_url` with the
same credential until the operation reports `succeeded`, `failed`,
or `needs_review`. Repeating the same action while it is pending
returns the same operation.
headers:
Location:
description: The `poll_url`.
schema:
type: string
Retry-After:
description: Always `2`.
schema:
type: string
example: '2'
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The computer UUID.
status:
type: string
enum:
- starting
- stopping
operation_id:
type: string
format: uuid
operation:
$ref: '#/components/schemas/ComputerOperation'
poll_url:
type: string
example:
id: a3bb189e-8bf9-3888-9912-ace4e6543002
status: stopping
operation_id: 5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
operation:
id: 5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
desktop_id: a3bb189e-8bf9-3888-9912-ace4e6543002
action: stop
status: queued
result: null
error: null
created_at: '2026-04-07T10:35:00Z'
updated_at: '2026-04-07T10:35:00Z'
poll_url: >-
/api/computers/a3bb189e-8bf9-3888-9912-ace4e6543002/operations/5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
poll_url: >-
/api/computers/a3bb189e-8bf9-3888-9912-ace4e6543002/operations/5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
'400':
description: >-
The computer's operating system or hardware cannot be archived
(`STOP_UNSUPPORTED`, or `DEVICE_LIFECYCLE_UNSUPPORTED` for a device
Orgo manages directly), the body is not empty and is not a JSON
object with an optional boolean `async`, or the `async` query
parameter is neither `true` nor `false`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unsupported:
summary: Cannot be archived
value:
error: >-
Stop isn’t available for macOS computers. Use Restart
instead.
code: STOP_UNSUPPORTED
body:
summary: Bad body
value:
error: >-
Expected a JSON object with an optional boolean async
field.
query:
summary: Bad query value
value:
error: async must be true or false
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: >-
The computer is a trial computer, which cannot be archived, or its
trial has ended.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
trial-archive:
summary: Trial computer
value:
error: Choose a plan to archive this computer.
code: TRIAL_ARCHIVE_UNAVAILABLE
trial:
summary: Trial ended
value:
error: Choose a plan to continue.
'403':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: >-
The stop was refused. A host that refuses the archive answers with
its own `4xx` status and `code`.
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
operation_id:
type: string
description: >-
Present on a failure that happened while the operation
ran.
poll_url:
type: string
examples:
not-stoppable:
summary: Not `running` and not `frozen`
value:
error: 'Computer is not running (status: stopped)'
code: not_stoppable
migrating:
summary: Being moved to another host
value:
error: >-
This computer is being moved to another host. Try again in
a few minutes.
code: migrating
in-progress:
summary: A start is still pending
value:
error: A different operation is already in progress.
code: OPERATION_IN_PROGRESS
needs-review:
summary: An earlier operation is in `needs_review`
value:
error: >-
The previous operation was interrupted and is being
checked. Try again in a few minutes.
code: OPERATION_NEEDS_REVIEW
'500':
description: >-
The archive or teardown failed. Check the operation status before
retrying; an uncertain result is fenced as `needs_review`.
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
operation_id:
type: string
description: >-
Present on a failure that happened while the operation
ran.
poll_url:
type: string
example:
error: …
code: …
'503':
description: >-
The computer has no host on record yet (`NOT_READY`), archived-disk
storage is not configured for this fleet (`frozen_disabled`), or the
credential could not be verified because of a server-side fault
(carries `Retry-After: 5`).
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
operation_id:
type: string
description: >-
Present on a failure that happened while the operation
ran.
poll_url:
type: string
examples:
not-ready:
summary: No host yet
value:
error: Computer not ready. VMM has not assigned a server yet
code: NOT_READY
frozen-disabled:
summary: Archive storage not configured
value:
error: …
code: frozen_disabled
auth:
summary: Credential could not be verified
value:
error: >-
Service temporarily unavailable. The database is not
accepting requests. Retry shortly.
headers:
Retry-After:
description: Present, as `5`, on the credential-verification fault.
schema:
type: string
components:
schemas:
ComputerOperation:
type: object
properties:
id:
type: string
format: uuid
desktop_id:
type: string
format: uuid
action:
type: string
enum:
- start
- stop
status:
type: string
enum:
- queued
- running
- succeeded
- failed
- needs_review
result:
type:
- object
- 'null'
description: 'On success, such as `{ "success": true }`.'
error:
type:
- object
- 'null'
description: 'On failure: `error`, `code`, and `status`.'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
poll_url:
type: string
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
responses:
Unauthorized:
description: 'No usable credential. Send `Authorization: Bearer $ORGO_API_KEY`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
AccessDenied:
description: >-
You are not the owner or a member of the computer's workspace, you have
view-only access, or the API key is scoped to another workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no-access:
summary: Not the owner or a member of the workspace
value:
error: You do not have access to this workspace.
view-only:
summary: View-only member, and the request changes something
value:
error: >-
This workspace is view-only. Ask the owner for write access
(workspace_read_only).
scope-mismatch:
summary: The API key is scoped to another workspace
value:
error: >-
This API key cannot access this workspace
(workspace_scope_mismatch).
NotFound:
description: No computer with this id on your account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Desktop not found
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.