​
Overview

The Orgo API enables you to programmatically create and manage virtual computer environments. Build automation workflows, integrate Orgo into your applications, or manage your desktop instances at scale.

​
Authentication

Authenticate your requests using a Bearer token in the Authorization header: 
Authorization: Bearer your_api_key
Get your API key from the Orgo dashboard.

​
Base URL

https://www.orgo.ai/api

​
Response Format

All responses are JSON-formatted with the following structure:

​
Success Response

{
  "id": "project_id",
  "name": "computer-abc123",
  "status": "active",
  "desktop": {
    "id": "instance_id",
    "status": "running",
    "url": "https://computer-abc123.orgo.dev"
  }
}

​
Error Response

{
  "error": "Error message description"
}

​
Resource Limits

​
Free Tier

  • 2 concurrent desktops maximum
  • Choose between:
    • 1× 4GB RAM desktop (4 CPU cores)
    • 2× 2GB RAM desktops (2 CPU cores each)

​
Configuration Options

  • RAM: 2GB or 4GB
  • CPU: 2 or 4 cores
  • Desktop instances automatically stop during inactivity

​
Quick Start

​
1. Create a Desktop

curl -X POST https://www.orgo.ai/api/projects \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"config": {"ram": 2, "cpu": 2}}'

​
2. Control the Desktop

Once created, use the project name (e.g., computer-abc123) to control it: 
# Take a screenshot
curl https://www.orgo.ai/api/computers/computer-abc123/screenshot \
  -H "Authorization: Bearer your_api_key"

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

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

​
Desktop Control Details

​
Mouse Operations

The click endpoint supports multiple mouse actions: 
// Left click (default)
{"x": 100, "y": 200}

// Right click
{"x": 100, "y": 200, "button": "right"}

// Double click
{"x": 100, "y": 200, "double": true}

​
Keyboard Input

​
Typing Text

Use the /type endpoint for regular text input: 
{"text": "This will be typed character by character"}

​
Key Presses

Use the /key endpoint for special keys and shortcuts: 
// Single keys (case-insensitive)
{"key": "Enter"}
{"key": "enter"}  // Both work
{"key": "Tab"}
{"key": "Escape"}
{"key": "space"}

// Key combinations with + (case-insensitive)
{"key": "ctrl+c"}    // Copy
{"key": "ctrl+v"}    // Paste
{"key": "ctrl+a"}    // Select all
{"key": "alt+tab"}   // Switch windows
{"key": "ctrl+shift+i"}  // Multi-modifier
Common key mappings:
  • enter → Return
  • escape or esc → Escape
  • tab → Tab
  • space → space

​
Scrolling

Scroll at specific coordinates: 
// Scroll down 3 units (default)
{"x": 500, "y": 300, "direction": "down"}

// Scroll up 5 units
{"x": 500, "y": 300, "direction": "up", "amount": 5}

​
Command Execution

​
Bash Commands

Execute shell commands: 
{"command": "ls -la"}
{"command": "cd /home/user && pwd"}

​
Python Code

Execute Python code with timeout protection: 
{
  "code": "print('Hello from Python')\nfor i in range(5):\n    print(i)",
  "timeout": 10  // Optional, defaults to 10 seconds
}
The Python environment includes:
  • Display environment pre-configured (DISPLAY=:1)
  • X11 authorization set up
  • Standard library available
  • Execution timeout to prevent infinite loops

​
Screenshots

Screenshots are returned as base64-encoded JPEG images: 
{
  "success": true,
  "image": "base64_encoded_image_data...",
  "metadata": {
    "id": "screenshot_id",
    "timestamp": "2024-01-20T10:30:00Z",
    "size": 245632,
    "storage_path": "screenshots/..."
  }
}

​
Wait/Delay

Add delays between actions: 
{"duration": 2.5}  // Wait 2.5 seconds

​
Project Management

​
List Projects

curl https://www.orgo.ai/api/projects \
  -H "Authorization: Bearer your_api_key"

​
Get Project by Name

curl https://www.orgo.ai/api/projects/by-name/computer-abc123 \
  -H "Authorization: Bearer your_api_key"

​
Desktop Lifecycle

# Stop a desktop (saves resources)
curl -X POST https://www.orgo.ai/api/projects/{id}/stop \
  -H "Authorization: Bearer your_api_key"

# Start a stopped desktop
curl -X POST https://www.orgo.ai/api/projects/{id}/start \
  -H "Authorization: Bearer your_api_key"

# Restart a desktop
curl -X POST https://www.orgo.ai/api/projects/{id}/restart \
  -H "Authorization: Bearer your_api_key"

# Delete project and desktop
curl -X POST https://www.orgo.ai/api/projects/{id}/delete \
  -H "Authorization: Bearer your_api_key"

​
Implementation Notes

  • All desktop control uses xdotool under the hood for reliable automation
  • Screenshots are captured using scrot at 100% quality
  • Commands execute in a real Linux desktop environment
  • Each desktop runs in an isolated container with its own filesystem
  • X11 display is available for GUI applications

​
Rate Limits & Timeouts

  • API requests have a 60-second timeout
  • Python code execution has a configurable timeout (default 10 seconds)
  • Screenshot operations are optimized for performance
  • Contact support for rate limit increases or custom requirements

​
Error Handling

The API returns appropriate HTTP status codes:
  • 200 - Success
  • 400 - Bad request (invalid parameters)
  • 401 - Authentication failed
  • 403 - Resource limit exceeded
  • 404 - Project/resource not found
  • 500 - Server error
All errors include a descriptive message in the response.

​
Next Steps

API Endpoints

Explore all available endpoints

SDK Quickstart

Use our Python or Node.js SDKs

Claude Integration

Build AI agents with Claude

Authentication

Set up API authentication