GatePilot API Documentation

Overview

Mobile identity for production agent workflows.

GatePilot combines a physical mobile device, real SIM, carrier mobile IP, assigned phone metadata, and route health into one proxy identity layer.

Identity unitOne physical device, SIM, carrier IP, and phone metadata

Pricing primitive$100 per device per month, unlimited high-speed data

Runtime fitPlaywright, Puppeteer, Browserbase, custom agents

Control modeExpose route health and proxy session status

Quickstart

Reserve a device, then attach your browser agent.

Create an API key

Generate a live key from the account dashboard. Keys are revealed once and should stay server-side.

List provisioned devices

Read the customer devices that admin has physically provisioned and assigned to your account.

Create a session

Start a browser session for the device and receive one-time proxy credentials.

Attach your browser runtime

Use the returned proxy endpoint with Playwright, Puppeteer, Browserbase, or your own agent runtime.

Environment

export GATEPILOT_API_KEY="gp_live_..."
export GATEPILOT_BASE_URL="https://gatepilot.ai/api/v1"
export GATEPILOT_PROXY_URL="https://proxy.gatepilot.ai"

List devices

curl "$GATEPILOT_BASE_URL/devices" \
  -H "Authorization: Bearer $GATEPILOT_API_KEY"

Create session

curl -X POST "$GATEPILOT_BASE_URL/sessions" \
  -H "Authorization: Bearer $GATEPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "org_device_...",
    "agent_id": "browser-agent-42",
    "timeout_seconds": 900
  }'

Device lifecycle

Manage the physical device as the identity boundary.

The device lifecycle keeps the hardware, SIM, phone metadata, session, route health, and assigned proxy identity tied together.

Provision	GatePilot admin assigns a physical router, SIM, phone metadata, gateway, and WireGuard tunnel IP to the paid mobile identity slot.
List	Find provisioned customer devices and supported capabilities through `GET /devices`.
Session	Create a time-bound browser session and receive one-time proxy credentials.
Route	Use the returned proxy metadata in Playwright, Puppeteer, Browserbase, or a custom runtime.
Expire	Sessions expire automatically at the requested timeout.

Browser integrations

Use the browser runtime you already ship.

GatePilot is exposed as an authenticated network identity, so agent teams can keep their browser orchestration layer and route session traffic through the assigned device.

Playwright

import { chromium } from 'playwright';

const gatepilotSession = await fetch(`${process.env.GATEPILOT_BASE_URL}/sessions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GATEPILOT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    device_id: process.env.GATEPILOT_DEVICE_ID,
    agent_id: 'browser-agent-42',
  }),
}).then((response) => response.json());

const browser = await chromium.launch({
  proxy: {
    server: gatepilotSession.proxy_url,
    username: gatepilotSession.proxy_username,
    password: gatepilotSession.proxy_password,
  },
});

const page = await browser.newPage();
await page.goto('https://example.com');

Browserbase

import { Browserbase } from '@browserbasehq/sdk';

const bb = new Browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY,
});

const gatepilotSession = await fetch(`${process.env.GATEPILOT_BASE_URL}/sessions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GATEPILOT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    device_id: process.env.GATEPILOT_DEVICE_ID,
    agent_id: 'browserbase-agent-42',
  }),
}).then((response) => response.json());

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  proxies: [{
    type: 'external',
    server: gatepilotSession.proxy_url,
    username: gatepilotSession.proxy_username,
    password: gatepilotSession.proxy_password,
  }],
});

console.log(session.connectUrl);

Launch scope

The pilot API is intentionally focused on proxy identity.

Launch sessions provide dedicated mobile egress through manually provisioned hardware. Domain allowlists, SMS workflows, and audit export APIs are not part of this pilot contract.

Route readiness

Sessions require a provisioned device, active gateway, worker socket, and fresh LTE egress health.

Unsupported fields

Launch sessions reject approved domain fields so clients do not assume policy enforcement exists.

Manual provisioning

Paid device slots are physically provisioned by operators before users receive proxy credentials or launch sessions.

API reference

Preview external API surface.

These endpoint shapes document the intended v1 contract for pilot integrations under https://gatepilot.ai/api/v1. Treat any operation marked Pilot as access-controlled until it is enabled in your GatePilot account.

GET/devices

Pilot

List provisioned devices

Returns provisioned devices assigned to the API key organization, with customer-safe route health.

AuthBearer API key

Request

No request body.

Response

{
  "devices": [{
    "id": "org_device_...",
    "label": "gatepilot-wg-01 / cudy-10.77.0.2",
    "status": "provisioned",
    "capabilities": ["mobile_ip", "phone_number"],
    "health": {
      "inventoryStatus": "assigned",
      "gatewayStatus": "active",
      "ready": true
    }
  }]
}

POST/sessions

Pilot

Create a browser session

Starts a time-bound session through the device and returns proxy credentials.

AuthBearer API key

Request

{
  "device_id": "org_device_...",
  "agent_id": "browser-agent-42",
  "timeout_seconds": 900
}

Response

{
  "session_id": "sess_...",
  "device_id": "org_device_...",
  "proxy_url": "https://proxy.gatepilot.ai",
  "proxy_username": "session_uuid",
  "proxy_password": "returned_once_...",
  "status": "running",
  "expires_at": "2026-05-16T20:15:00Z"
}

Errors and limits

Design for unavailable hardware and unsupported fields.

Physical devices can be provisioning, offline, or route-unready. Clients should handle retryable states explicitly.

Status	Code	Meaning
400	`UNSUPPORTED_FIELD`	`approved_domains` and `approvedDomains` are not supported in launch sessions.
401	`UNAUTHORIZED`	Missing, revoked, or invalid API key.
404	`NOT_FOUND`	Device or session was not found for the project.
409	`DEVICE_UNAVAILABLE`	The requested physical device is not provisioned, assigned, or online.
429	`RATE_LIMITED`	The project exceeded request, rotation, or session limits.

Session timeout, rotation frequency, bandwidth, and available countries are account-level pilot settings. United States devices are the launch geography; additional countries are handled through design partner requests.