> ## 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.
# Get computer
> Retrieve a computer by ID.
Returns a computer's details, including its current status and everything needed to connect to it.
## Path parameters
Computer UUID or `instance_id`. Both resolve to the same computer.
## Response
Computer identifier (UUID).
Computer name.
ID of the parent workspace.
Name of the parent workspace.
What you can do in the computer's workspace: `canView`, `canWrite`, and `canManageAccess`, each a boolean.
The computer's placement and connection record, with every field whose name contains `password`, `secret`, `token`, `api_key`, or `authorized_keys` removed.
Operating system: `linux`, `windows`, `macos`, `android`, or `ios`.
RAM in GB.
vCPU. Fractional for `0.5` vCPU computers.
One of `creating`, `running`, `restarting`, `updating`, `suspended`, `frozen`, `stopped`, `error`, `deleted`. See [Status values](#status-values).
The computer's API address on its fleet host, as `http://{host}:{port}`. This is an internal fleet address, not a dashboard link and not the endpoint you connect to. Use `connection_url` to connect. The value is rewritten whenever the computer restarts, is started again, or has its RAM resized. It still holds the last host's address after the computer is stopped, so it is only meaningful while the computer is `running`.
Stable identifier for the underlying compute instance. It is the same value `POST /computers` returns as `instance_id`. Use it to build `connection_url` and to reference the computer across restarts. `null` while the computer has no host (`frozen`). This endpoint returns the field under its legacy name only.
ISO 8601 timestamp.
Same-origin host for the computer's connection endpoints: `www.orgo.ai`. Empty while the computer has no instance id, such as when it is `frozen`.
Same-origin connection base (`https://www.orgo.ai/desktops/{instance_id}`). Append `/ws/websockify`, `/ws/terminal`, or `/ws/audio` for the WebSocket endpoints; HTTP Desktop API calls go to `https://www.orgo.ai/api/desktops/{instance_id}/proxy/{endpoint}`. Empty while the computer has no instance id, such as when it is `frozen`.
Current VNC / WebSocket token. Rotates on restart, on start, and on a RAM resize. `null` when you have view-only access to the workspace, or when the stored credential cannot be decrypted.
`true` when the computer's workspace keeps screens private, so the Orgo dashboard keeps the screen covered until someone chooses to show it.
What the computer runs on, from its current VM's launch record: `host_cpu` (`family`, `name`, and `signature`, or `null`), `cpu_model`, `hypervisor`, `qemu`, `boot`, `fallback`, and `launched_at`. `null` when the host has not reported a launch record for the computer's current VM.
### Status values
| Status | Meaning |
| - | - |
| `creating` | The record exists and the computer is being provisioned. |
| `running` | The computer is up on a host and reachable. |
| `restarting` | A [restart](/api-reference/computers/restart) is in flight. |
| `updating` | An in-place OS image update is in flight. |
| `suspended` | Paused on its host. It resumes on interaction, not through [start](/api-reference/computers/start). |
| `frozen` | Stopped. The disk is archived to object storage and no host is held. This is what [stop](/api-reference/computers/stop) produces. |
| `stopped` | The computer was not found on its host, or its host reported a terminal state. Like `frozen`, it can be started again. |
| `error` | Its host reported the computer in an error state when a restart or OS update did not finish. Like `stopped`, it can be started again. |
| `deleted` | Tombstoned after its archived disk passed the retention window. |
## Example
```bash cURL theme={null}
curl https://www.orgo.ai/api/computers/$COMPUTER_ID \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import requests
response = requests.get(
f"https://www.orgo.ai/api/computers/{computer_id}",
headers={"Authorization": f"Bearer {api_key}"}
)
computer = response.json()
print(f"Status: {computer['status']}")
```
```javascript JavaScript theme={null}
const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}`, {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const computer = await response.json();
console.log(`Status: ${computer.status}`);
```
### Response
```json theme={null}
{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"permissions": { "canView": true, "canWrite": true, "canManageAccess": true },
"instance_details": {
"provider": "metal",
"id": "a3881618",
"name": "a3881618",
"webUrl": "http://162.43.189.25:8231",
"vncHost": "162.43.189.25",
"vncPort": 8232,
"apiPort": 8231,
"serverAddress": "http://10.0.0.4:9000",
"resolution": "1280x720x24",
"fromPool": false
},
"name": "agent-1",
"project_name": "production",
"os": "linux",
"ram": 4,
"cpu": 1,
"status": "running",
"url": "http://162.43.189.25:8231",
"fly_instance_id": "a3881618",
"created_at": "2026-04-07T10:35:00Z",
"hostname": "www.orgo.ai",
"connection_url": "https://www.orgo.ai/desktops/a3881618",
"vnc_password": "a06db12a8683df96",
"private_screens": false,
"hardware": null
}
```
## Errors
| Status | Body | When |
| - | - | - |
| `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 continue." }` | The computer is a trial computer whose trial has ended. |
| `403` | `{ "error": "You do not have access to this workspace." }` | You are neither the owner nor a member of the computer's 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. |
| `500` | `{ "error": "…" }` | Lookup failed. |
| `503` | `{ "error": "Service temporarily unavailable. The database is not accepting requests. Retry shortly." }` | The credential store is unavailable. Carries `Retry-After: 5`. |
## Rename a computer
`PATCH /computers/{id}` updates a computer's name and its mascot. It takes the same path parameter as `GET`, and requires that you **own** the workspace. A view-only member gets `403`, and a member with write access who is not the owner gets `404` with `Access denied`.
New computer name. Omitted leaves the name alone; an empty or non-string value returns `400`.
The computer's mascot look, with all fields optional: `color` (`stone`, `pearl`, `graphite`, `ink`, `green`, `blue`, `red`, `orange`, `purple`, `cyan`, `pink`, `yellow`, `teal`, `coral`), `expression` (`deadpan`, `friendly`, `focused`, `thinking`, `excited`, `sleepy`, `surprised`, `skeptical`, `worried`, `mischievous`), and `accessory` (`none`, `beanie`, `tophat`, `party`, `glasses`, `sunglasses`, `bow`). Unrecognised fields and values are dropped rather than rejected, so a field you send with an unknown value falls back to the default. `null` clears the mascot; omitting the field leaves it alone; any other non-object value returns `400`.
The response is the updated record, not the full computer object. It carries `id`, `name`, `bot_mascot` (`null` when unset), and `updated_at`.
```bash theme={null}
curl -X PATCH https://www.orgo.ai/api/computers/$COMPUTER_ID \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "agent-1-renamed", "bot_mascot": {"color": "teal", "expression": "focused"}}'
```
```json theme={null}
{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"name": "agent-1-renamed",
"bot_mascot": { "color": "teal", "expression": "focused" },
"updated_at": "2026-04-07T11:02:14.000Z"
}
```
| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "Computer name cannot be empty" }` | `name` is present but empty or not a string. |
| `400` | `{ "error": "bot_mascot must be an object or null" }` | `bot_mascot` is neither an object nor `null`. |
| `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 continue." }` | The computer is a trial computer whose trial has ended. |
| `403` | `{ "error": "You do not have access to this workspace." }` | You are neither the owner nor a member of the workspace. |
| `403` | `{ "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)." }` | You are a view-only member. |
| `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" }` or `{ "error": "Access denied" }` | No computer matches the id, or you are a member with write access but not the workspace owner. |
| `500` | `{ "error": "…" }` | The update failed, for example because another computer in the workspace already has that `name`, or the body is not valid JSON. |
| `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. |
## OpenAPI
````yaml GET /computers/{id}
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}:
get:
tags:
- Computers
summary: Get computer
description: >-
Returns a computer's details, including its current status and
everything needed to connect. Accepts the computer UUID or its
`instance_id`.
operationId: getComputer
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
responses:
'200':
description: Computer details
content:
application/json:
schema:
$ref: '#/components/schemas/Computer'
example:
id: a3bb189e-8bf9-3888-9912-ace4e6543002
project_id: 550e8400-e29b-41d4-a716-446655440000
permissions:
canView: true
canWrite: true
canManageAccess: true
instance_details:
provider: metal
id: a3881618
name: a3881618
webUrl: http://162.43.189.25:8231
vncHost: 162.43.189.25
vncPort: 8232
apiPort: 8231
serverAddress: http://10.0.0.4:9000
resolution: 1280x720x24
fromPool: false
name: agent-1
project_name: production
os: linux
ram: 4
cpu: 1
status: running
url: http://162.43.189.25:8231
fly_instance_id: a3881618
created_at: '2026-04-07T10:35:00Z'
hostname: www.orgo.ai
connection_url: https://www.orgo.ai/desktops/a3881618
vnc_password: a06db12a8683df96
private_screens: false
hardware: null
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/TrialInactive'
'403':
$ref: '#/components/responses/AccessDeniedRead'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: Lookup failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: …
'503':
$ref: '#/components/responses/AuthUnavailable'
components:
schemas:
Computer:
type: object
properties:
id:
type: string
description: Unique computer identifier
example: a3bb189e-8bf9-3888-9912-ace4e6543002
name:
type: string
description: Computer name
example: agent-1
workspace_id:
type: string
description: >-
ID of the workspace the computer belongs to. Returned by `POST
/computers`; `GET /computers/{id}` returns it as `project_id`.
example: 550e8400-e29b-41d4-a716-446655440000
project_name:
type: string
description: Name of the parent workspace
example: production
os:
type: string
enum:
- linux
- windows
- macos
- android
- ios
description: >-
Operating system. `ios` is a physical handset rather than a virtual
computer.
example: linux
ram:
type: integer
enum:
- 4
- 8
- 12
- 16
- 32
- 64
description: RAM in GB. `12` occurs only on macOS.
example: 4
cpu:
type: number
enum:
- 0.5
- 1
- 2
- 4
- 8
- 16
description: vCPU cores.
example: 1
status:
type: string
enum:
- creating
- running
- restarting
- updating
- suspended
- frozen
- stopped
- error
- deleted
description: Current status
example: running
url:
type: string
description: >-
Base URL of the computer's own API on the host that runs it, as
`http://:`. Plain HTTP, and reachable only from inside
Orgo's network. It is not a dashboard link and not an endpoint you
can call. Use `connection_url` from your own code.
example: http://198.51.100.24:8081
created_at:
type: string
format: date-time
instance_id:
type: string
description: >-
Stable identifier for the underlying compute instance, returned by
`POST /computers`. Use it for connection URLs and to reference the
computer across restarts. `GET /computers/{id}` returns the same
value as `fly_instance_id`.
example: a3881618
hostname:
type: string
description: >-
Same-origin host for the computer's connection endpoints:
`www.orgo.ai`. Empty while the computer has no instance id, such as
when it is `frozen`.
example: www.orgo.ai
connection_url:
type: string
description: >-
Same-origin connection base
(https://www.orgo.ai/desktops/{instance_id}). Append /ws/websockify,
/ws/terminal, or /ws/audio for WebSocket endpoints; HTTP Desktop API
calls go to
https://www.orgo.ai/api/desktops/{instance_id}/proxy/{endpoint}.
example: https://www.orgo.ai/desktops/a3881618
vnc_password:
type:
- string
- 'null'
description: >-
VNC / WebSocket Bearer token. Rotates on restart, on start, and on a
RAM resize, so do not persist it. `null` when you have view-only
access to the workspace, or when the stored credential cannot be
decrypted.
example: a06db12a8683df96
project_id:
type: string
description: >-
ID of the parent workspace, under its older name. `POST /computers`
returns it as a deprecated alias of `workspace_id`; `GET
/computers/{id}` returns only this name.
example: 550e8400-e29b-41d4-a716-446655440000
fly_instance_id:
type:
- string
- 'null'
description: >-
The instance id under its legacy name. The same value `POST
/computers` returns as `instance_id`. `GET /computers/{id}` returns
only this name. `null` while the computer has no host (`frozen`).
example: a3881618
permissions:
$ref: '#/components/schemas/Permissions'
private_screens:
type: boolean
description: >-
Returned by `GET /computers/{id}`. `true` when the computer's
workspace keeps screens private, so the Orgo dashboard keeps the
screen covered until someone chooses to show it.
example: false
instance_details:
type: object
additionalProperties: true
description: >-
The computer's placement and connection record: `provider`, `id`,
`name`, `webUrl`, `vncHost`, `vncPort`, `apiPort`, `serverAddress`,
`resolution`, and `fromPool`, plus `hypervisor` and
`templateTerminals` when they apply. `GET /computers/{id}` and the
workspace endpoints remove every field whose name contains
`password`, `secret`, `token`, `api_key`, or `authorized_keys`, in
any letter case and at any depth.
hardware:
type:
- object
- 'null'
description: >-
What the computer runs on, from its current VM's launch record. `GET
/computers/{id}` always returns it, `null` when the host has not
reported a launch record for the computer's current VM. `POST
/computers` returns it, with `launch`, only when the host reports
how it launched the computer.
properties:
host_cpu:
type:
- object
- 'null'
description: >-
The host's CPU, or `null` when the launch record does not name
it.
properties:
family:
type:
- string
- 'null'
name:
type:
- string
- 'null'
signature:
type:
- string
- 'null'
cpu_model:
type:
- string
- 'null'
description: '`host`, or the named CPU model the guest was given.'
hypervisor:
type:
- string
- 'null'
description: '`qemu` or `firecracker`.'
qemu:
type:
- string
- 'null'
description: The QEMU version that ran the computer.
boot:
type:
- string
- 'null'
description: How the computer last booted.
fallback:
type:
- string
- 'null'
description: >-
Set when the launch could not do what it was asked and fell
back, such as a resume that cold-booted because the CPU
differed.
launched_at:
type:
- string
- 'null'
format: date-time
launch:
type: object
additionalProperties: true
description: >-
Returned by `POST /computers` alongside `hardware`, when the host
reports how it launched the computer: the host's launch record for
the new computer, without the host's name or the source its state
was restored from.
resolution:
type: string
description: >-
Display resolution in `WIDTHxHEIGHTxDEPTH` format. Returned by `POST
/computers`.
example: 1280x720x24
gpu_downgraded:
type: boolean
description: >-
Returned by `POST /computers` only, present and `true` when you
asked for a `gpu` and a CPU computer was created instead.
warning:
type: string
description: Present only alongside `gpu_downgraded`, explaining the downgrade.
description: >-
A computer. No single response carries every field: `POST /computers`
returns `workspace_id`, `project_id`, `instance_id`, `fly_instance_id`,
and the connect fields, plus `hardware` and `launch` when the host
reports them; `GET /computers/{id}` returns `project_id`,
`project_name`, `permissions`, `fly_instance_id`, the connect fields,
`private_screens`, and `hardware`; a computer embedded in a workspace
carries the stored row. Each operation's example shows what that
operation returns.
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.
Permissions:
type: object
description: What your role in the workspace allows.
properties:
canView:
type: boolean
example: true
canWrite:
type: boolean
description: '`false` for a view-only member.'
example: true
canManageAccess:
type: boolean
description: Only the owner has it.
example: true
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
TrialInactive:
description: >-
The computer is a free trial computer whose trial is no longer active,
or it is paid for by its own subscription or dedicated purchase and that
payment has lapsed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
trial:
summary: Trial no longer active
value:
error: Choose a plan to continue.
payment:
summary: The computer's own payment has lapsed
value:
error: Manage this computer’s payment in Account → Usage.
AccessDeniedRead:
description: >-
You are not the owner or a member of the workspace, 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.
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
AuthUnavailable:
description: >-
Orgo could not verify the credential because of a server-side fault,
such as a database outage. Retry after `Retry-After`. Do not rotate the
key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
headers:
Retry-After:
description: Seconds to wait before retrying. Always `5`.
schema:
type: string
example: '5'
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.