> ## 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.

# API Reference

> Build with virtual computers programmatically

The Orgo API provisions virtual computers and controls them programmatically. Use it to run agent fleets, automation workflows, or browser testing.

## Base URL

```text theme={null}
https://www.orgo.ai/api
```

## Authentication

All requests require a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer $ORGO_API_KEY
```

Get your API key at [orgo.ai/start](https://www.orgo.ai/start). See [Authentication](/api-reference/authentication) for key scopes and what they do and do not restrict.

## Quick start

### 1. Create a workspace

Workspaces organize your computers.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/workspaces \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-workspace"}'
```

### 2. Create a computer

```bash theme={null}
curl -X POST https://www.orgo.ai/api/computers \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"workspace_id\": \"$WORKSPACE_ID\", \"name\": \"agent-1\", \"os\": \"linux\", \"ram\": 4, \"cpu\": 1}"
```

### 3. Control the computer

```bash theme={null}
# Take a screenshot
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/screenshot \
  -H "Authorization: Bearer $ORGO_API_KEY"

# Click at coordinates
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'

# Type text
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/type \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world"}'

# Run a bash command
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/bash \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}'
```

## Resource hierarchy

```text theme={null}
User
└── Workspaces
    └── Computers
```

Workspaces group related computers together. Use them to separate environments (production, staging) or projects.

## Computer specs

| Parameter | Values the API accepts | Default when omitted |
| - | - | - |
| `os` | `linux`, `windows`, `macos`, `android`, `ios` | `linux` |
| `cpu` | 0.5, 1, 2, 4, 8, 16 cores | 1, or the template's size when you pass `template_ref` |
| `ram` | 4, 8, 16, 32, 64 GB (macOS also accepts 12) | 4, or the template's size when you pass `template_ref` |
| `disk_size_gb` | 1 up to your plan's per-computer maximum | The template's disk when you pass `template_ref`. Otherwise set by your plan: 40 GB on current paid plans, 20 GB on legacy plans, and never above the plan's per-computer maximum (8 GB on Free). |
| `gpu` | `2q` (2 GB VRAM), `4q` (4 GB VRAM) | none |
| `resolution` | `WIDTHxHEIGHTxDEPTH` (e.g. `1024x768x24`, `1920x1080x24`) | `1280x720x24` (`1920x1080x24` on macOS), or the template's when you pass `template_ref` |

Any other value for `os`, `cpu`, `ram`, or `gpu` is rejected with `400`. `ios` places the computer on a physical handset, so it succeeds only where one is available, and `cpu` and `ram` are ignored for it. GPU computers are Linux only. Windows requires either a Windows license on the account or a plan that includes Windows.

Maximum CPU, RAM, and disk per computer are capped by your plan. See [orgo.ai/pricing](https://orgo.ai/pricing).

### Recommended configurations

| RAM | CPU | Best for |
| - | - | - |
| 4 GB | 1 core | Standard workflows (default) |
| 8 GB | 2 cores | Heavier automation |
| 16 GB | 4 cores | Development |
| 32 GB | 8 cores | Large-scale processing |

## Available actions

### Mouse

* Click (left, right, double)
* [Move](/api-reference/computers/mouse-move) (hover, without clicking)
* Drag
* Scroll

### Keyboard

* Type text
* Press keys (Enter, Tab, ctrl+c, etc.)

### Execution

* Bash commands
* Python code

### Real-time (WebSocket)

* [Terminal](/api-reference/computers/terminal): interactive PTY shell
* [Audio](/api-reference/computers/audio): live PCM audio stream from the computer's virtual speaker
* [Events](/api-reference/computers/events): subscribe to window, clipboard, file, process, and idle events

### Lifecycle

* Start, stop, restart
* Auto-stop (off by default; configurable per computer on paid plans)
* Clone (copy a computer with full disk state)
* Fork (copy a running computer, memory included)
* Resize (live CPU/RAM/disk hot-resize)
* Move (transfer between workspaces)

### Other

* Screenshots
* Wait/delays

## Templates

[Templates](/guides/templates/introduction) are reproducible computers defined in a single `orgo.ai/v1` file: hardware, installed apps, long-running services, secrets, and lifecycle hooks. Orgo builds the file once into a golden snapshot, and every launch restores from it in seconds.

* **Launch a curated template.** Pass a `system/…` ref as `template_ref` to [Create computer](/api-reference/computers/create).
* **Author your own.** [Validate](/api-reference/templates/validate), [publish](/api-reference/templates/publish), and [build](/api-reference/templates/build) over HTTP. Start at the [Templates API](/api-reference/templates/schema).

Template authoring availability depends on your plan. See [orgo.ai/pricing](https://orgo.ai/pricing).

## Resource IDs

Workspaces, computers, files, and threads are identified by UUIDs. Pass the UUID in the URL path wherever you see an `{id}` placeholder, as in `/workspaces/{id}` or `/computers/{id}/click`.

Workspace and computer UUIDs are returned in the `id` field of every create, get, and list response. A computer also has a separate instance id, returned as `instance_id` by [Create computer](/api-reference/computers/create). The instance id addresses WebSocket paths such as `wss://www.orgo.ai/desktops/{instance_id}/ws/websockify`, not the REST endpoints.

## Error responses

Errors return a JSON object with an `error` field holding a human-readable message:

```json theme={null}
{
  "error": "Invalid API key"
}
```

The OpenAI-compatible endpoints under `/v1` are the exception. Their `error` is an object with `type`, `message`, and `code`, described in [Create chat completion](/api-reference/chat/completions#errors).

Some errors add a machine-readable `code` (for example `workspace_scope_mismatch`, `GUEST_RESTRICTED`, `disk_exceeds_quota`). Branch on `code` where it is present. It is stable, and the `error` string is not.

Workspaces are called projects internally, so a few error messages on the workspace endpoints say "project". They refer to the same resource.

| Status | Meaning |
| - | - |
| `200` | Success |
| `201` | Created |
| `204` | Success with no body (destroying a screen) |
| `207` | Partial success (resize only: some dimensions applied, others rejected) |
| `400` | Invalid request: bad JSON, missing required field, out-of-range value |
| `401` | Invalid API key (`Invalid API key`) or no API key (`Authentication required`). Some endpoints also answer an access or scope failure with `401`. |
| `402` | Payment required: the credit balance is too low, a free trial computer can no longer run, or a computer paid for on its own has a lapsed payment |
| `403` | Authenticated, but not allowed: plan limit exceeded, workspace scope mismatch, view-only access, or no access to the resource |
| `404` | Resource not found |
| `405` | Method not allowed. Check the verb for the endpoint. |
| `409` | Conflict: the resource is in a state that blocks this operation (e.g. resizing a computer that is not running) |
| `422` | Validation failed: all dimensions of a resize were rejected |
| `429` | Rate limited. Back off and retry. |
| `500` | Unexpected server error |
| `501` | Not supported on this computer's operating system (for example `exec` on an iPhone) |
| `502` | The computer was asked to do something and did not confirm it (for example placing an uploaded file) |
| `503` | Orgo, or the computer, could not be reached. Retry after the `Retry-After` delay when the response carries one. |
| `504` | A command on the computer ran past its allowed time (`bash` and `exec`) |

## Rate limits

Some endpoints are rate limited. If you get a `429`, back off with exponential retry: start at 1s, double each retry, and cap the delay at 60s. Email [spencer@orgo.ai](mailto:spencer@orgo.ai) if you need higher limits.

## Next steps

<CardGroup cols={2}>
  <Card title="Create Workspace" icon="folder" href="/api-reference/workspaces/create">
    Organize computers
  </Card>

  <Card title="Create Computer" icon="desktop" href="/api-reference/computers/create">
    Provision a computer
  </Card>

  <Card title="Templates" icon="layer-group" href="/api-reference/templates/schema">
    Reproducible computers
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key setup
  </Card>

  <Card title="Use Any Model" icon="robot" href="/guides/models">
    Claude, GPT, Gemini, and more
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.