# Orgo API

> Desktop infrastructure for AI agents. Launch headless cloud VMs that AI models can control and interact with.

## Base URL

https://www.orgo.ai/api

## Authentication

All requests require a Bearer token:
```
Authorization: Bearer sk_live_...
```

Get your API key at https://www.orgo.ai/workspaces

## Endpoints

### Workspaces

- POST /workspaces - Create a workspace
- GET /workspaces - List all workspaces
- GET /workspaces/{id} - Get workspace by ID
- DELETE /workspaces/{id} - Delete workspace

### Computers

- POST /computers - Create a computer
  - Required: workspace_id, name
  - Optional: os (linux), ram (4/8/16/32/64), cpu (2/4/8/16), gpu, resolution (WIDTHxHEIGHTxDEPTH, default 1280x720x24)
- GET /computers/{id} - Get computer by ID
- DELETE /computers/{id} - Delete computer
- GET /computers/{id}/vnc-password - Get VNC password

### Computer Lifecycle

- POST /computers/{id}/start - Start computer
- POST /computers/{id}/stop - Stop computer
- POST /computers/{id}/restart - Restart computer

### Computer Actions

- GET /computers/{id}/screenshot - Take screenshot (returns base64 PNG)
- POST /computers/{id}/click - Click mouse
  - Required: x, y
  - Optional: button (left/right), double (boolean)
- POST /computers/{id}/drag - Drag mouse
  - Required: start_x, start_y, end_x, end_y
  - Optional: button, duration
- POST /computers/{id}/type - Type text
  - Required: text
- POST /computers/{id}/key - Press key
  - Required: key (e.g., "Enter", "Tab", "ctrl+c")
- POST /computers/{id}/scroll - Scroll
  - Required: direction (up/down)
  - Optional: amount (default: 3)
- POST /computers/{id}/wait - Wait
  - Required: duration (seconds)
- POST /computers/{id}/bash - Execute bash command
  - Required: command
- POST /computers/{id}/exec - Execute Python code
  - Required: code
  - Optional: timeout (default: 10)

### WebSocket (Real-time)

- WS /terminal - Interactive PTY terminal
  - URL: wss://{computer_id}.orgo.dev/terminal?token={password}&cols=80&rows=24
  - Auth: password from GET /computers/{id}/vnc-password
  - Client sends: input (data), resize (cols, rows), ping
  - Server sends: output (data), exit (code), pong, error (message)

- WS /audio - Live PCM audio stream
  - URL: wss://{computer_id}.orgo.dev/audio?token={password}
  - Format: s16le 24kHz mono, 20ms frames (960 bytes), ~48 KB/s
  - Server sends JSON "started" frame, then binary PCM frames
  - Client sends: stop, ping

- WS /events - Desktop event stream
  - URL: wss://{computer_id}.orgo.dev/events?token={password}
  - Subscribe: {"type": "subscribe", "event_types": ["window_focus", "clipboard"]}
  - Event types: window_focus, window_open, window_close, clipboard, file_change,
    screen_change, audio_stream_start, audio_stream_stop, process_start,
    process_stop, idle, active
  - Events arrive as: {"type": "event", "event": {"type": "...", "timestamp": "...", "data": {...}}}

### Streaming

- POST /computers/{id}/stream/start - Start RTMP stream
  - Required: connection_name
- GET /computers/{id}/stream/status - Get stream status
- POST /computers/{id}/stream/stop - Stop stream

### Files

- POST /files/upload - Upload file (multipart/form-data)
  - Required: file, projectId (workspace ID)
  - Optional: desktopId (computer ID)
- GET /files - List files
  - Required: projectId (workspace ID)
  - Optional: desktopId (computer ID)
- POST /files/export - Export file from computer
  - Required: desktopId, path
- GET /files/download - Get download URL
  - Required: id (query param)
- DELETE /files/delete - Delete file
  - Required: id (query param)

## Computer Specs

| Parameter | Options | Default |
|-----------|---------|---------|
| os | linux | linux |
| ram | 4, 8, 16, 32, 64 GB | 4 |
| cpu | 2, 4, 8, 16 cores | 2 |
| gpu | none, a10, l40s, a100-40gb, a100-80gb | none |

## Quick Start

1. Create a workspace:
```bash
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
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"}'
```

3. Take a screenshot:
```bash
curl https://www.orgo.ai/api/computers/COMPUTER_ID/screenshot \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

4. Click at coordinates:
```bash
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}'
```

## SDKs

- Python: `pip install orgo`
- TypeScript: `npm install orgo`

## Documentation

Full documentation: https://docs.orgo.ai