The Orchestrator API provides programmatic access to browser-as-a-service functionality. Create, manage, and interact with browser sessions through a simple REST API.

​
Base URL

All API requests should be made to: 
https://api.orchestratorhq.com

​
API Overview

The Orchestrator API is organized around REST principles with predictable resource-oriented URLs. It accepts and returns JSON-encoded requests and responses, and uses standard HTTP response codes and authentication.

​
Core Concepts

Sessions

Browser instances that can be accessed via VNC or Chrome DevTools Protocol (CDP)

Organizations

All resources are scoped to your organization for team collaboration

Authentication

Secure API access using API keys or JWT tokens

Real-time Access

Connect to live browser sessions via WebSocket protocols

​
Quick Start

Here’s a simple example of creating and using a browser session: 
# Create a session
curl -X POST https://api.orchestratorhq.com/api/sessions \
  -H "Authorization: Bearer orch_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"session_name": "My First Session", "duration": "1h"}'

# Get session access details
curl https://api.orchestratorhq.com/api/sessions/sess_abc123/access \
  -H "Authorization: Bearer orch_your_api_key_here"

​
Session Lifecycle

Understanding the session lifecycle is key to using the API effectively:
1

Create Session

Use POST /api/sessions to create a new browser session with your desired configuration.
2

Wait for Active Status

Sessions start in “creating” status and transition to “active” when ready for use.
3

Get Access Information

Use GET /api/sessions/{id}/access to retrieve VNC and CDP connection details.
4

Connect and Automate

Connect your automation tools (Playwright, Puppeteer, etc.) using the provided endpoints.
5

Manage Session

Monitor, extend, or stop sessions as needed using the management endpoints.

​
Status Codes

The API uses standard HTTP status codes to indicate success or failure:
CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
402Payment Required - Insufficient credits
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
503Service Unavailable - No servers available

​
Rate Limits

API requests are rate limited per organization:
  • Free tier: 100 requests per minute
  • Pro tier: 500 requests per minute
  • Max tier: 1000 requests per minute
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642694400

​
Need Help?

Authentication Guide

Learn how to authenticate your API requests

Create Your First Session

Step-by-step guide to creating browser sessions