Orgo - Cloud computers for AI agents

POST

computers

{id}

key

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/key \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "key": "Return"
}
'

{
  "success": true,
  "action": "key_press",
  "details": {
    "key": "Return"
  },
  "error": null,
  "error_type": null
}

Presses a key or key combination. Join a combination with +, for example ctrl+shift+t.

On a Windows computer the response is {"ok": true}. Key names are not case-sensitive and follow Windows naming, so Page_Up and Page_Down are spelled pageup and pagedown; the other keys in the tables below work as written. A missing or unrecognised key returns 400 rather than 500, and the error body reads Request failed with status code 400 rather than saying why. ?screen= is ignored.

Path parameters

string

required

Computer ID (UUID). An instance_id is not accepted here and fails with 500.

Query parameters

string

Which screen to press the key on. Optional. Omit it to act on the screen the computer booted with. An unknown id returns 404 rather than falling back to the default screen.

Body parameters

string

required

Key or key combination to press. On Linux the value is passed through to the computer’s keyboard driver unchanged, so it must be an X11 keysym name. Keysym names are case-sensitive. Nothing validates the field before it gets there: a missing or misspelled key surfaces as a 500, not a 400.

Common keys

Use the keysym name, not the label printed on the key. Return and BackSpace are the two that most often catch people out.

Key	Description
`Return`	Enter/Return key
`Tab`	Tab key
`Escape`	Escape key
`BackSpace`	Backspace key
`Delete`	Forward delete
`space`	Space bar
`Up`, `Down`, `Left`, `Right`	Arrow keys
`Home`, `End`	Home/End keys
`Page_Up`, `Page_Down`	Page navigation
`F1`-`F12`	Function keys

Common combinations

Combination	Description
`ctrl+c`	Copy
`ctrl+v`	Paste
`ctrl+a`	Select all
`ctrl+s`	Save
`alt+Tab`	Switch windows
`alt+F4`	Close window
`ctrl+shift+t`	Reopen closed tab

The modifier names are ctrl, alt, shift, and super.

Response

boolean

Always true on a 200. A key the computer could not press is an error status.

string

Always key_press.

object

Carries key, an echo of what was sent.

null

Always null on a 200.

null

Always null on a 200.

Example

# Press Return
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/key \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "Return"}'

# Ctrl+C
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/key \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "ctrl+c"}'

import requests

url = f"https://www.orgo.ai/api/computers/{computer_id}/key"
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

# Press Return
requests.post(url, headers=headers, json={"key": "Return"})

# Ctrl+C
requests.post(url, headers=headers, json={"key": "ctrl+c"})

const url = `https://www.orgo.ai/api/computers/${computerId}/key`;
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

// Press Return
await fetch(url, { method: 'POST', headers, body: JSON.stringify({ key: 'Return' }) });

// Ctrl+C
await fetch(url, { method: 'POST', headers, body: JSON.stringify({ key: 'ctrl+c' }) });

Response

{
  "success": true,
  "action": "key_press",
  "details": { "key": "Return" },
  "error": null,
  "error_type": null
}

Errors

Status	Meaning
`400`	The computer has no VM attached: `{"error": "Desktop instance not available"}`. Also returned by the computer agent when `key` is not a JSON string. A missing or unrecognised `key` is not a `400`: it is a `500`.
`401`	Invalid API key: `{"error": "Invalid API key"}`. A request with no `Authorization` header returns `{"error": "Authentication required"}`. Access failures also return `401` on this endpoint, not `403`: `{"error": "You do not have access to this workspace."}` when you are neither the owner nor a member of the computer’s workspace, `{"error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)."}` for a view-only member, and `{"error": "This API key cannot access this workspace (workspace_scope_mismatch)."}` for a workspace-scoped key used outside its workspace. A server-side fault while verifying the credential also returns `401`, with `{"error": "Service temporarily unavailable. The database is not accepting requests. Retry shortly."}`. Retry that one; the key is fine.
`402`	The computer was created as a free trial that is no longer active: `{"error": "Choose a plan to continue."}`.
`404`	No computer with this id: `{"error": "Desktop not found"}`. Also returned by the computer agent when `?screen=` names a screen this computer does not have, as in `{"error": "no screen \"2\"", "request_id": "…", "upstream_status": 404}`.
`500`	The computer could not press the key. A missing, misspelled, or non-keysym value lands here. Also returned when the request body is not valid JSON, with the parser’s message in `error`.
`503`	The computer could not be reached: `{"error": "Could not reach the desktop. Try again in a moment.", "code": "ECONNREFUSED"}`. Safe to retry. Also returned when the computer never finished provisioning: `{"error": "Computer not ready"}`.

Every failure raised after the request leaves the API layer also carries a request_id. Quote it in support requests. When the computer agent itself answered non-2xx, the body additionally carries upstream_status.

{
  "error": "pressing key \"Enter\": exit status 1",
  "request_id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "upstream_status": 500
}

Authorizations

Authorization

string

header

required

API key authentication. Get your key at orgo.ai/workspaces

Path Parameters

string

required

Computer ID

Query Parameters

screen

string

Which screen to act on. Omit for the boot screen. An unknown id returns 404 rather than falling back.

Body

application/json

key

string

required

Key or key combination (e.g., Enter, Tab, ctrl+c, alt+F4). On an iPhone: home, app_switcher, Return, BackSpace, space.

Example:

"Return"

Response

Key pressed

success

boolean

Always true on a 200. A failed action is an error status.

Example:

true

action

string

The action performed: click, mouse_move, drag, type, key_press, scroll, or wait.

details

object

Echo of what was performed. Its fields depend on the action.

error

null

Always null on a 200.

error_type

null

Always null on a 200.

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/key \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "key": "Return"
}
'

{
  "success": true,
  "action": "key_press",
  "details": {
    "key": "Return"
  },
  "error": null,
  "error_type": null
}

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Press key

Path parameters

Query parameters

Body parameters

Common keys

Common combinations

Response

Example

Response

Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

​Path parameters

​Query parameters

​Body parameters

​Common keys

​Common combinations

​Response

​Example

​Response

​Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

Path parameters

Query parameters

Body parameters

Common keys

Common combinations

Response

Example

Response

Errors