GatePilot API Documentation

Overview

Rack-backed mobile identity for agent workflows.

A GatePilot device is a physical device in a managed rack with a real SIM, carrier-backed mobile IP, dedicated phone number, policy controls, and audit logs. The API is designed for authorized production agents that need continuity across browser, network, and phone identity.

Identity unitOne physical device, SIM, IP, and phone number

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

Runtime fitPlaywright, Puppeteer, Browserbase, custom agents

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 against the provisioned device and receive the proxy credentials for that run.

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",
    "approved_domains": ["example.com"],
    "timeout_seconds": 900
  }'

Device lifecycle

Manage the physical device as the agent identity boundary.

The device lifecycle keeps the hardware, SIM, phone number, policy, session, and logs tied together. Treat the reservation as the stable identity for the agent, and sessions as time-bound network routes through that identity.

Provision	GatePilot admin assigns a physical router, SIM, phone number, gateway, and WireGuard tunnel IP to the paid device slot.
List	Find provisioned customer devices and supported capabilities through `GET /devices`.
Session	Create a time-bound browser session for approved domains and policies.
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 only the approved session traffic through the assigned mobile 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',
    approved_domains: ['example.com'],
  }),
}).then((response) => response.json());

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

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',
    approved_domains: ['example.com'],
  }),
}).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: process.env.GATEPILOT_API_KEY,
  }],
});

console.log(session.connectUrl);

Governance

Policies and logs are part of the integration surface.

GatePilot supports authorized business automation. Device sessions should run against approved domains, route through defined policies, and produce audit events that let teams review what happened.

Domain controls

Constrain sessions to the web properties approved for the project.

Operational limits

Apply timeouts, rotation controls, data limits, and team-level API key hygiene.

Audit trail

Record device reservation, session creation, policy blocks, and lifecycle events.

Export audit events

curl "$GATEPILOT_BASE_URL/audit/events?session_id=sess_..." \
  -H "Authorization: Bearer $GATEPILOT_API_KEY"

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

Preview

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

Preview

Create a browser session

Starts a time-bound session through the provisioned device and returns one-time proxy credentials for the agent runtime.

AuthBearer API key

Request

{
  "device_id": "org_device_...",
  "agent_id": "browser-agent-42",
  "approved_domains": ["example.com"],
  "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 policy blocks.

Physical devices can be provisioned, offline, rotating, or constrained by policy. Clients should handle retryable states explicitly and never assume a requested rack device is immediately available.

Status	Code	Meaning
401	`UNAUTHORIZED`	Missing, revoked, or invalid API key.
403	`POLICY_BLOCKED`	The requested domain, route, or action is outside the approved policy.
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.