Creates browser windows (tabs) inside a session, loads URLs, reads window info, and closes windows. A window is the unit that pages load into and that page-interaction and AI-query operations act on.
openapi: 3.0.1
info:
title: Airtop API
description: >-
REST API for Airtop, a cloud-browser platform for AI agents. Create and
manage remote Chromium browser sessions, open and navigate windows, drive
pages with natural-language interactions (click, type, hover, scroll),
query and extract page content with AI, capture screenshots, and persist
state with profiles. All requests are authenticated with a Bearer API key.
termsOfService: https://www.airtop.ai/legal/terms-of-service
contact:
name: Airtop Support
url: https://docs.airtop.ai
version: '1.0'
servers:
- url: https://api.airtop.ai/api/v1
description: Airtop production API
security:
- bearerAuth: []
tags:
- name: Sessions
description: Create and manage cloud browser sessions.
- name: Windows
description: Create, navigate, and close browser windows inside a session.
- name: Page Interaction
description: Drive a page with natural-language click, type, hover, and scroll.
- name: AI Query
description: Query, extract, and scrape page content with AI.
- name: Screenshots
description: Capture window screenshots.
- name: Profiles
description: Persist and delete browser profiles.
paths:
/sessions:
get:
operationId: listSessions
tags:
- Sessions
summary: List sessions
description: Returns the cloud browser sessions for the authenticated account.
parameters:
- name: offset
in: query
required: false
schema:
type: integer
- name: limit
in: query
required: false
schema:
type: integer
- name: status
in: query
required: false
schema:
type: string
responses:
'200':
description: A list of sessions.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionsListResponse'
post:
operationId: createSession
tags:
- Sessions
summary: Create session
description: >-
Starts a new cloud browser session (a remote Chromium instance) with
optional profile, proxy, recording, captcha solving, and idle timeout
configuration. Returns connection URLs (CDP and WebDriver) for the
live session.
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/SessionConfig'
responses:
'200':
description: The created session.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse'
/sessions/{sessionId}:
get:
operationId: getSession
tags:
- Sessions
summary: Get session info
description: Returns details and status for a single session.
parameters:
- $ref: '#/components/parameters/SessionId'
responses:
'200':
description: The session.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse'
delete:
operationId: terminateSession
tags:
- Sessions
summary: Terminate session
description: Ends a session and releases its cloud browser resources.
parameters:
- $ref: '#/components/parameters/SessionId'
responses:
'200':
description: Session terminated.
content:
application/json:
schema:
$ref: '#/components/schemas/EnvelopeResponse'
/sessions/{sessionId}/profile:
put:
operationId: saveProfileOnTermination
tags:
- Profiles
summary: Save profile on termination
description: >-
Marks a named profile to be persisted (cookies, local storage,
authenticated state) when the session terminates, so it can be loaded
into a future session.
parameters:
- $ref: '#/components/parameters/SessionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
profileName:
type: string
description: Name to save the persisted browser profile under.
required:
- profileName
responses:
'200':
description: Profile save scheduled.
content:
application/json:
schema:
$ref: '#/components/schemas/EnvelopeResponse'
/sessions/{sessionId}/windows:
get:
operationId: listWindows
tags:
- Windows
summary: List windows
description: Lists the windows currently open in a session.
parameters:
- $ref: '#/components/parameters/SessionId'
responses:
'200':
description: A list of windows.
content:
application/json:
schema:
$ref: '#/components/schemas/WindowsListResponse'
post:
operationId: createWindow
tags:
- Windows
summary: Create window
description: >-
Opens a new browser window (tab) in a session and optionally navigates
it to a URL.
parameters:
- $ref: '#/components/parameters/SessionId'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWindowRequest'
responses:
'200':
description: The created window.
content:
application/json:
schema:
$ref: '#/components/schemas/WindowResponse'
/sessions/{sessionId}/windows/{windowId}:
get:
operationId: getWindowInfo
tags:
- Windows
summary: Get window info
description: >-
Returns information about a window, including a live-view URL and
current navigation state.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
responses:
'200':
description: The window.
content:
application/json:
schema:
$ref: '#/components/schemas/WindowResponse'
delete:
operationId: closeWindow
tags:
- Windows
summary: Close window
description: Closes a window within a session.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
responses:
'200':
description: Window closed.
content:
application/json:
schema:
$ref: '#/components/schemas/EnvelopeResponse'
/sessions/{sessionId}/windows/{windowId}/load-url:
post:
operationId: loadUrl
tags:
- Windows
summary: Load URL
description: Navigates an existing window to a new URL.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
description: The URL to navigate to.
waitUntil:
type: string
enum: [load, domContentLoaded, complete, noWait]
description: Navigation event to wait for before returning.
waitUntilTimeoutSeconds:
type: integer
default: 30
required:
- url
responses:
'200':
description: Navigation complete.
content:
application/json:
schema:
$ref: '#/components/schemas/WindowResponse'
/sessions/{sessionId}/windows/{windowId}/click:
post:
operationId: click
tags:
- Page Interaction
summary: Click
description: >-
Clicks an element identified by a natural-language description. AI
resolves the description to an on-page target before clicking.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClickRequest'
responses:
'200':
description: Click performed.
content:
application/json:
schema:
$ref: '#/components/schemas/AIResponse'
/sessions/{sessionId}/windows/{windowId}/hover:
post:
operationId: hover
tags:
- Page Interaction
summary: Hover
description: Hovers over an element described in natural language.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ElementInteractionRequest'
responses:
'200':
description: Hover performed.
content:
application/json:
schema:
$ref: '#/components/schemas/AIResponse'
/sessions/{sessionId}/windows/{windowId}/type:
post:
operationId: type
tags:
- Page Interaction
summary: Type
description: >-
Types text into a field described in natural language, with options to
clear the field first and press Enter afterward.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TypeRequest'
responses:
'200':
description: Text typed.
content:
application/json:
schema:
$ref: '#/components/schemas/AIResponse'
/sessions/{sessionId}/windows/{windowId}/scroll:
post:
operationId: scroll
tags:
- Page Interaction
summary: Scroll
description: Scrolls the page, optionally toward a described element or by an offset.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ScrollRequest'
responses:
'200':
description: Scroll performed.
content:
application/json:
schema:
$ref: '#/components/schemas/AIResponse'
/sessions/{sessionId}/windows/{windowId}/screenshot:
get:
operationId: takeScreenshot
tags:
- Screenshots
summary: Take screenshot
description: Captures a screenshot of the current state of a window.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
responses:
'200':
description: The screenshot.
content:
application/json:
schema:
$ref: '#/components/schemas/ScreenshotResponse'
/sessions/{sessionId}/windows/{windowId}/scrape:
post:
operationId: scrapeContent
tags:
- AI Query
summary: Scrape content
description: Scrapes the raw content of the page loaded in a window.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ScrapeRequest'
responses:
'200':
description: Scraped content.
content:
application/json:
schema:
$ref: '#/components/schemas/AIResponse'
/sessions/{sessionId}/windows/{windowId}/page-query:
post:
operationId: pageQuery
tags:
- AI Query
summary: Query a page
description: >-
Asks a natural-language question about the current page and returns an
AI model response, optionally shaped by a JSON output schema.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PageQueryRequest'
responses:
'200':
description: The AI model response.
content:
application/json:
schema:
$ref: '#/components/schemas/AIResponse'
/sessions/{sessionId}/windows/{windowId}/paginated-extraction:
post:
operationId: paginatedExtraction
tags:
- AI Query
summary: Query a page with pagination
description: >-
Extracts structured data from a page and follows pagination links to
gather results across multiple pages.
parameters:
- $ref: '#/components/parameters/SessionId'
- $ref: '#/components/parameters/WindowId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedExtractionRequest'
responses:
'200':
description: The extracted data.
content:
application/json:
schema:
$ref: '#/components/schemas/AIResponse'
/profiles/{profileId}:
delete:
operationId: deleteProfile
tags:
- Profiles
summary: Delete profile
description: Deletes a persisted browser profile.
parameters:
- name: profileId
in: path
required: true
schema:
type: string
responses:
'200':
description: Profile deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/EnvelopeResponse'
/requests/{requestId}:
get:
operationId: getRequestStatus
tags:
- Sessions
summary: Get request status
description: >-
Returns the status and result of an asynchronous request previously
issued against the API.
parameters:
- name: requestId
in: path
required: true
schema:
type: string
responses:
'200':
description: The request status.
content:
application/json:
schema:
$ref: '#/components/schemas/EnvelopeResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Airtop API key supplied as a Bearer token in the Authorization header:
`Authorization: Bearer YOUR_API_KEY`.
parameters:
SessionId:
name: sessionId
in: path
required: true
description: Identifier of the cloud browser session.
schema:
type: string
WindowId:
name: windowId
in: path
required: true
description: Identifier of the window within the session.
schema:
type: string
schemas:
Envelope:
type: object
properties:
meta:
type: object
properties:
requestId:
type: string
status:
type: string
errors:
type: array
items:
type: object
warnings:
type: array
items:
type: object
EnvelopeResponse:
allOf:
- $ref: '#/components/schemas/Envelope'
- type: object
properties:
data:
type: object
SessionConfig:
type: object
properties:
configuration:
type: object
properties:
profileName:
type: string
description: Name of a profile to load into the session.
extensionIds:
type: array
items:
type: string
description: Chrome Web Store extension IDs to load.
proxy:
description: Proxy configuration (boolean, object, or array).
oneOf:
- type: boolean
- type: object
- type: array
items:
type: object
record:
type: boolean
description: Enable session recording.
solveCaptcha:
type: boolean
description: Automatically solve captcha challenges.
timeoutMinutes:
type: integer
default: 10
description: Idle timeout in minutes before the session ends.
Session:
type: object
properties:
id:
type: string
status:
type: string
cdpWsUrl:
type: string
description: Chrome DevTools Protocol WebSocket URL for the session.
cdpUrl:
type: string
webDriverUrl:
type: string
profileName:
type: string
SessionResponse:
allOf:
- $ref: '#/components/schemas/Envelope'
- type: object
properties:
data:
$ref: '#/components/schemas/Session'
SessionsListResponse:
allOf:
- $ref: '#/components/schemas/Envelope'
- type: object
properties:
data:
type: object
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/Session'
CreateWindowRequest:
type: object
properties:
url:
type: string
format: uri
description: Initial URL to load in the window.
screenResolution:
type: string
default: 1280x720
description: Window viewport resolution.
waitUntil:
type: string
enum: [load, domContentLoaded, complete, noWait]
waitUntilTimeoutSeconds:
type: integer
default: 30
Window:
type: object
properties:
windowId:
type: string
targetId:
type: string
url:
type: string
title:
type: string
liveViewUrl:
type: string
WindowResponse:
allOf:
- $ref: '#/components/schemas/Envelope'
- type: object
properties:
data:
$ref: '#/components/schemas/Window'
WindowsListResponse:
allOf:
- $ref: '#/components/schemas/Envelope'
- type: object
properties:
data:
type: object
properties:
windows:
type: array
items:
$ref: '#/components/schemas/Window'
ElementInteractionRequest:
type: object
properties:
elementDescription:
type: string
description: Natural-language description of the target element.
clientRequestId:
type: string
costThresholdCredits:
type: integer
timeThresholdSeconds:
type: integer
configuration:
type: object
required:
- elementDescription
ClickRequest:
allOf:
- $ref: '#/components/schemas/ElementInteractionRequest'
- type: object
properties:
configuration:
type: object
properties:
clickType:
type: string
enum: [click, doubleClick, rightClick]
visualAnalysis:
type: object
waitForNavigationConfig:
type: object
waitForNavigation:
type: boolean
TypeRequest:
type: object
properties:
text:
type: string
description: The text to type.
elementDescription:
type: string
description: Natural-language description of the field to type into.
pressEnterKey:
type: boolean
description: Press Enter after typing.
clearInputField:
type: boolean
description: Clear the field before typing.
clientRequestId:
type: string
costThresholdCredits:
type: integer
timeThresholdSeconds:
type: integer
configuration:
type: object
required:
- text
ScrollRequest:
type: object
properties:
scrollToElement:
type: string
description: Natural-language description of an element to scroll to.
scrollBy:
type: object
description: Pixel offset to scroll by.
configuration:
type: object
PageQueryRequest:
type: object
properties:
prompt:
type: string
description: The question or instruction for analyzing page content.
clientRequestId:
type: string
followPaginationLinks:
type: boolean
default: false
costThresholdCredits:
type: integer
timeThresholdSeconds:
type: integer
configuration:
type: object
properties:
outputSchema:
type: object
description: JSON schema describing the desired structured output.
scrape:
type: object
visualAnalysis:
type: object
experimental:
type: object
required:
- prompt
PaginatedExtractionRequest:
type: object
properties:
prompt:
type: string
clientRequestId:
type: string
costThresholdCredits:
type: integer
timeThresholdSeconds:
type: integer
configuration:
type: object
properties:
outputSchema:
type: object
paginationMode:
type: string
enum: [auto, paginated, infinite-scroll]
required:
- prompt
ScrapeRequest:
type: object
properties:
clientRequestId:
type: string
costThresholdCredits:
type: integer
timeThresholdSeconds:
type: integer
configuration:
type: object
AIResponse:
allOf:
- $ref: '#/components/schemas/Envelope'
- type: object
properties:
data:
type: object
properties:
modelResponse:
type: string
description: The AI model's textual response to the prompt.
meta:
type: object
properties:
requestId:
type: string
status:
type: string
usage:
type: object
properties:
credits:
type: number
screenshots:
type: array
items:
type: object
ScreenshotResponse:
allOf:
- $ref: '#/components/schemas/Envelope'
- type: object
properties:
data:
type: object
properties:
screenshots:
type: array
items:
type: object
properties:
dataUrl:
type: string
description: Base64 data URL of the captured screenshot.