> ## 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.
# Create a screen
> Start another screen on the same computer.
Starts another screen on a computer that is already running. Use a second
screen when two agents need to work at the same time. X11 has a single pointer
per display, so two agents sharing one screen are two hands on one mouse.
A Linux computer supports at most four screens. Each one is an X server plus a
window manager plus whatever runs on it, so a computer runs out of memory
long before it runs out of screens.
Extra screens are a Linux feature. A macOS computer or an iPhone has exactly
one screen, so this endpoint answers `409` there. A Windows computer has no
screens endpoints, so it answers `404`.
## Path parameters
Computer ID (UUID). The computer must be up. One that is still being created,
or that has been frozen, returns `400`.
## Body parameters
Width in pixels. Send `width` and `height` together or send neither.
Height in pixels. Send `width` and `height` together or send neither.
If either dimension is missing or zero, **both** fall back to the size of the
boot screen. The value you did send is discarded and no error is returned. On
a 1920×1080 computer, `{"width": 1280}` returns a 1920×1080 screen, not a
1280×1080 one.
Send an empty body to match the screen the computer booted with. That is almost
always the size you want for a second screen.
## Response
Returns the new [screen](/api-reference/screens/list) with `201`. Pass its `id`
as `?screen=` to target it from
[screenshot](/api-reference/computers/screenshot),
[click](/api-reference/computers/click),
[move mouse](/api-reference/computers/mouse-move),
[type](/api-reference/computers/type),
[key](/api-reference/computers/key),
[scroll](/api-reference/computers/scroll),
[drag](/api-reference/computers/drag) and
[bash](/api-reference/computers/bash). An action sent without the parameter
acts on the boot screen.
Orgo records the new screen before it answers, so a restart or start brings it
back with the same id, as described in
[Screens after a restart](/api-reference/screens/list#screens-after-a-restart).
A created screen gets a window manager and nothing else: no panel, no
wallpaper, no icons. That is deliberate. Each of those costs memory on every
screen, and an agent reads none of it. A screenshot of a fresh screen is an
empty root window, which is what a working screen looks like before anything
has been opened on it.
## 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" }` |
| `400` | `width` or `height` is not an integer. | `{ "error": "invalid JSON: …", "request_id": "…", "upstream_status": 400 }` |
| `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` | You have view-only access to the workspace. | `{ "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)." }` |
| `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 }` |
| `409` | The computer is already at four screens, or the new screen failed to start. A macOS computer or an iPhone always answers this, because it has one screen. | `{ "error": "…", "request_id": "…", "upstream_status": 409 }` |
| `500` | Unexpected failure. | `{ "error": "…", "request_id": "…" }` |
| `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 -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/screens \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
```json 201 theme={null}
{
"id": "screen-100",
"display": ":100",
"width": 1920,
"height": 1080,
"vnc_port": 6000,
"ws_port": 6081,
"default": false
}
```
```json 409 theme={null}
{
"error": "this VM already has 4 screens, which is the limit",
"request_id": "7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7",
"upstream_status": 409
}
```
## OpenAPI
````yaml POST /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:
post:
tags:
- Screens
summary: Create a screen
description: >-
Starts another screen on the computer. Omit `width` and `height` to
match the boot screen. A Linux computer supports at most four screens. A
macOS computer or an iPhone has exactly one screen and answers `409`. A
Windows computer has no screens endpoints and answers `404`. Orgo
records the new screen before answering, so a restart or start brings it
back with the same id.
operationId: createScreen
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ScreenRequest'
examples:
match-default:
summary: Match the boot screen
value: {}
explicit-size:
summary: A specific size
value:
width: 1280
height: 720
responses:
'201':
description: Screen created
content:
application/json:
schema:
$ref: '#/components/schemas/Screen'
'400':
description: >-
The computer has nothing running behind it, or `width` or `height`
is not an integer.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/UpstreamError'
examples:
not-available:
summary: Nothing running
value:
error: Computer not available
bad-json:
summary: Not an integer
value:
error: 'invalid JSON: …'
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 400
'401':
$ref: '#/components/responses/UnauthorizedWithAccess'
'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
'409':
description: >-
A Linux computer is already at four screens, or the new screen
failed to start. A macOS computer or an iPhone always answers `409`,
because it has exactly one screen.
content:
application/json:
schema:
$ref: '#/components/schemas/UpstreamError'
examples:
limit:
summary: Linux computer at four screens
value:
error: this VM already has 4 screens, which is the limit
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 409
macos:
summary: A macOS computer
value:
error: >-
a macOS desktop has exactly one screen: macOS runs one
window server and one pointer per session, so a second,
independent screen cannot be added (it can on Linux, where
each screen is its own X server). Use a second computer
for a second agent
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 409
iphone:
summary: An iPhone
value:
error: >-
an iPhone has exactly one screen, so a second, independent
screen cannot be added (it can on Linux, where each screen
is its own X server). Use a second computer for a second
agent
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 409
'500':
description: Unexpected failure.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
example:
error: …
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
'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:
ScreenRequest:
type: object
properties:
width:
type: integer
description: Width in pixels. Omitted, the screen matches the boot screen.
example: 1920
height:
type: integer
description: Height in pixels. Omitted, the screen matches the boot screen.
example: 1080
description: >-
Size for a new screen. Send both dimensions or neither: if either is
missing or zero, both fall back to the size of the boot screen and the
value you did send is discarded without an error.
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
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.
responses:
UnauthorizedWithAccess:
description: >-
No usable credential, or an access check failed. This endpoint runs its
workspace access checks during authentication, so it answers a missing
membership, view-only access, 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.
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).
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.