> ## 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.
# List screens
> Every screen on a computer.
A Linux computer boots with one screen and can run up to four. Each screen is its own
X server, with its own root window, its own cursor, and its own window manager.
An agent working on one screen cannot disturb another.
Extra screens are a Linux feature. A macOS computer or an iPhone has exactly
one screen, and this endpoint lists it as `default` with a `display` that is
not an X display. A Windows computer has no screens endpoints, so it answers
`404`.
## Screens after a restart
Extra screens come back after a restart. Each time a
[create](/api-reference/screens/create), [resize](/api-reference/screens/resize),
or [destroy](/api-reference/screens/delete) succeeds, Orgo records the
computer's extra screens, with their ids and sizes, before it answers. After a
[restart](/api-reference/computers/restart), a
[start](/api-reference/computers/start), or a
[resize](/api-reference/computers/resize) that restarted the computer
(`restarted: true`), Orgo makes them again with the same ids, so the same
displays and ports. A [stop](/api-reference/computers/stop) keeps the record
with the computer's archive, so the start that follows brings them back too.
A screen comes back empty. A restart ends every process, so the windows that
were open on it are gone. The recreated screen has a window manager and nothing
else, like a newly created one.
Recreating screens is best effort:
* It happens in the background. The restart or start answers without waiting
for it. Orgo then waits up to three minutes for the computer to come up, and
makes each screen it is missing. List the screens to see which are back.
* A screen that cannot be made again is skipped, and the rest still come back.
* If the computer stops running before it comes up, nothing is made.
Screens are not made again after an OS update, after a backup restore, or after
a reboot that did not go through Orgo, such as `reboot` run on the computer
itself. A computer that Orgo stops because its owner's plan was downgraded does
not keep them either. The boot screen is never recorded, so a size you give
`default` with [resize](/api-reference/screens/resize) lasts only until the
next restart, when it is back at the size the computer boots with.
## Path parameters
Computer ID (UUID). The computer must be up. One that is still being created,
or that has been frozen, returns `400`.
## Response
Every screen on the computer, the boot screen first and the rest in display
order. Never empty while the computer is up.
Screen identifier. The boot screen is always `default`. A screen you
create is named after its display, so `:100` is `screen-100`. Pass this
value as `?screen=` on an action to target the screen.
X display. The boot screen is `:99`. Each created screen takes the lowest
free display number from `:100` up, so a number freed by a destroyed
screen is reused.
Width in pixels.
Height in pixels.
VNC port. Derived from the display rather than looked up: 5900 plus the
display number, so `:99` is 5999 and `:100` is 6000.
WebSocket port bridging that VNC stream: 5981 plus the display number, so
`:99` is 6080 and `:100` is 6081.
`true` for the screen the computer booted with. It cannot be destroyed.
## Errors
Failures raised before the request reaches the computer carry `error` alone.
Failures relayed back from the computer add `request_id` and `upstream_status`.
| Status | When | Body |
| - | - | - |
| `400` | The computer has nothing running behind it: still being created, or frozen. | `{ "error": "Computer not available" }` |
| `401` | The Bearer token starts with `sk_` but is not a known Orgo key. | `{ "error": "Invalid API key" }` |
| `401` | No `Authorization` header, or a Bearer token that is not an `sk_` key. | `{ "error": "Authentication required" }` |
| `401` | You do not own the computer's workspace and are not a member of it. | `{ "error": "You do not have access to this workspace." }` |
| `401` | The API key is scoped to a different workspace. | `{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }` |
| `401` | Orgo could not verify the credential because of a server-side fault. Retry. | `{ "error": "Service temporarily unavailable. …" }` |
| `402` | The computer is a free trial computer that can no longer run. | `{ "error": "Choose a plan to continue." }` |
| `402` | The computer is paid for by its own subscription or dedicated purchase, and that payment has lapsed. | `{ "error": "Manage this computer’s payment in Account → Usage." }` |
| `404` | No computer with that ID. | `{ "error": "Desktop not found" }` |
| `404` | The computer runs Windows, whose agent has no screens endpoint. | `{ "error": "…", "request_id": "…", "upstream_status": 404 }` |
| `500` | Unexpected failure. | `{ "error": "…", "request_id": "…" }` |
| `501` | A macOS computer or an iPhone whose agent cannot list screens, when Orgo has no screen size on file for it. | `{ "error": "…", "code": "SCREENS_UNSUPPORTED_OS" }` |
| `503` | The computer could not be reached. | `{ "error": "Could not reach the desktop. Try again in a moment.", "request_id": "…", "code": "ECONNREFUSED" }` |
```bash cURL theme={null}
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/screens \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```json 200 theme={null}
{
"screens": [
{ "id": "default", "display": ":99", "width": 1920, "height": 1080, "vnc_port": 5999, "ws_port": 6080, "default": true },
{ "id": "screen-100", "display": ":100", "width": 1920, "height": 1080, "vnc_port": 6000, "ws_port": 6081, "default": false }
]
}
```
## OpenAPI
````yaml GET /computers/{id}/screens
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}/screens:
get:
tags:
- Screens
summary: List screens
description: >-
Lists every screen on the computer, including the boot screen. A macOS
computer or an iPhone has exactly one screen. A Windows computer has no
screens endpoints and answers `404`. Extra screens come back after a
restart: Orgo records them whenever a create, resize, or destroy
succeeds, and makes them again with the same ids after a restart or
start. They come back empty, in the background, on a best-effort basis.
operationId: listScreens
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
responses:
'200':
description: The computer's screens
content:
application/json:
schema:
$ref: '#/components/schemas/ScreenListResponse'
'400':
description: >-
The computer has nothing running behind it: still being created, or
frozen.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Computer not available
'401':
$ref: '#/components/responses/UnauthorizedWithReadAccess'
'402':
$ref: '#/components/responses/TrialInactive'
'404':
description: >-
No computer with that ID, or the computer runs Windows, whose agent
has no screens endpoints.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/UpstreamError'
examples:
no-computer:
summary: Unknown computer
value:
error: Desktop not found
windows:
summary: A Windows computer
value:
error: |
404 page not found
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 404
'500':
description: Unexpected failure.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
example:
error: …
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
'501':
description: >-
A macOS computer or an iPhone whose agent cannot list its screens,
when Orgo has no screen size on file for it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: >-
This computer's agent can't list its screens yet, and Orgo has
no screen size on file for it. It has exactly one screen:
leave out `screen` and every action uses it.
code: SCREENS_UNSUPPORTED_OS
'503':
description: >-
The computer could not be reached. It may be resuming, or its host
may be unhealthy. Retry in a moment.
content:
application/json:
schema:
$ref: '#/components/schemas/UnreachableError'
example:
error: Could not reach the desktop. Try again in a moment.
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
code: ECONNREFUSED
components:
schemas:
ScreenListResponse:
type: object
properties:
screens:
type: array
items:
$ref: '#/components/schemas/Screen'
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.
UpstreamError:
type: object
description: >-
A failure the computer itself returned, relayed with the computer's own
status.
required:
- error
- request_id
- upstream_status
properties:
error:
type: string
description: The message the computer returned.
request_id:
type: string
description: >-
Correlation id for this failure. The server logged the failure under
it, so quote it in a support report.
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status:
type: integer
description: >-
The status the computer returned. Mirrors the status of this
response.
example: 409
InternalError:
type: object
description: >-
An unexpected failure. Retrying is reasonable; if it persists, quote
`request_id`.
required:
- error
properties:
error:
type: string
request_id:
type: string
description: >-
Present on failures raised by a route that talks to a computer.
Absent on the others.
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
UnreachableError:
type: object
description: >-
The computer could not be reached. The diagnostic fields, present on the
command endpoints, say how far the request got.
required:
- error
- request_id
- code
properties:
error:
type: string
example: Could not reach the desktop. Try again in a moment.
request_id:
type: string
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
code:
type: string
description: >-
The socket-level error code, or `network_error` when none was
reported.
example: ECONNREFUSED
vm_status:
type:
- string
- 'null'
description: The computer's recorded status when the request failed.
desired_status:
type:
- string
- 'null'
description: >-
The status the computer was being driven towards, when one was
recorded.
host_reachable:
type:
- boolean
- 'null'
description: Whether the host running the computer answered.
desktop_api_reachable:
type:
- boolean
- 'null'
description: Whether the computer's own API answered.
hint:
type: string
description: What to do next, given the two reachability results.
Screen:
type: object
properties:
id:
type: string
description: Screen identifier. The boot screen is always `default`.
example: screen-100
display:
type: string
description: X display this screen runs on.
example: ':100'
width:
type: integer
description: Width in pixels.
example: 1920
height:
type: integer
description: Height in pixels.
example: 1080
vnc_port:
type: integer
description: VNC port for this screen.
example: 6000
ws_port:
type: integer
description: WebSocket port for this screen.
example: 6081
default:
type: boolean
description: True for the screen the computer boots with. It cannot be destroyed.
example: false
responses:
UnauthorizedWithReadAccess:
description: >-
No usable credential, or an access check failed. This endpoint runs its
workspace access checks during authentication, so it answers a missing
membership or a key scoped to another workspace with `401`, not `403`. A
server-side fault while verifying the credential also returns `401`,
with a `Service temporarily unavailable` message. Retry that one; the
key is fine.
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
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).
service-unavailable:
summary: Server-side fault while verifying the credential. Retry.
value:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
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.
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.