API Reference

Fresh Source: docs.airtop.ai

Complete API endpoint reference for Airtop. All endpoints require an API key via the Authorization: Bearer <API_KEY> header.

Base URL: https://api.airtop.ai/v1

Sessions

Method	Endpoint	Description
GET	/sessions	List all active sessions
POST	/sessions	Create a new browser session
GET	/sessions/{sessionId}	Get session info and status
POST	/sessions/{sessionId}/terminate	Terminate a session
POST	/sessions/{sessionId}/save-profile	Save browser profile from session

Create Session

POST /sessions

Request Body:

{
  "configuration": {
    "timeoutMinutes": 10,
    "persistProfile": false,
    "profileName": "optional-profile-name",
    "solveCaptcha": false,
    "screenResolution": "1920x1080",
    "proxy": {
      "type": "airtop",
      "options": {
        "country": "US",
        "sticky": true
      }
    }
  }
}

Response:

{
  "data": {
    "id": "session-uuid",
    "status": "running",
    "cdpWsUrl": "wss://...",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

Terminate Session

POST /sessions/{sessionId}/terminate

Request Body (optional):

{
  "saveProfileOnTermination": "my-profile"
}

Windows

Method	Endpoint	Description
POST	/sessions/{sessionId}/windows	Create a new window
GET	/sessions/{sessionId}/windows	List windows in session
DELETE	/sessions/{sessionId}/windows/{windowId}	Close a window
POST	/sessions/{sessionId}/windows/{windowId}/click	Click an element
POST	/sessions/{sessionId}/windows/{windowId}/type	Type text into element
POST	/sessions/{sessionId}/windows/{windowId}/hover	Hover over element
POST	/sessions/{sessionId}/windows/{windowId}/scroll	Scroll the page
POST	/sessions/{sessionId}/windows/{windowId}/scrape	Scrape page content
POST	/sessions/{sessionId}/windows/{windowId}/page-query	Query page with AI
POST	/sessions/{sessionId}/windows/{windowId}/paginated-extraction	Multi-page extraction
POST	/sessions/{sessionId}/windows/{windowId}/prompt-content	Summarize/transform
POST	/sessions/{sessionId}/windows/{windowId}/screenshot	Take screenshot
POST	/sessions/{sessionId}/windows/{windowId}/monitor	Watch for condition
POST	/sessions/{sessionId}/windows/{windowId}/fill-form	AI form filling
POST	/sessions/{sessionId}/windows/{windowId}/form-filler	Alternative form fill

Create Window

POST /sessions/{sessionId}/windows

Request Body:

{
  "url": "https://example.com",
  "waitUntil": "load",
  "screenResolution": "1920x1080"
}

Page Query

POST /sessions/{sessionId}/windows/{windowId}/page-query

Request Body:

{
  "prompt": "What is the main heading?",
  "configuration": {
    "outputSchema": {
      "type": "object",
      "properties": {
        "heading": { "type": "string" }
      }
    },
    "costThresholdCredits": 10,
    "timeThresholdSeconds": 30
  }
}

Click Element

POST /sessions/{sessionId}/windows/{windowId}/click

Request Body:

{
  "elementDescription": "the Sign In button"
}

Type Text

POST /sessions/{sessionId}/windows/{windowId}/type

Request Body:

{
  "elementDescription": "the email input field",
  "text": "user@example.com"
}

Fill Form

POST /sessions/{sessionId}/windows/{windowId}/fill-form

Request Body:

{
  "customData": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

Monitor

POST /sessions/{sessionId}/windows/{windowId}/monitor

Request Body:

{
  "condition": "The price drops below $50",
  "configuration": {
    "intervalMs": 5000,
    "timeoutMs": 300000
  }
}

Automations

Method	Endpoint	Description
GET	/automations	List all automations
POST	/automations	Create an automation
PUT	/automations/{id}	Update an automation
DELETE	/automations/{id}	Delete an automation
GET	/automations/{id}	Get automation details
POST	/automations/{id}/execute	Execute automation asynchronously

Profiles

Method	Endpoint	Description
DELETE	/profiles/{profileId}	Delete a saved profile

Files

Method	Endpoint	Description
GET	/files	List uploaded files
POST	/files	Upload a file
GET	/files/{fileId}	Get file details
DELETE	/files/{fileId}	Delete a file
POST	/files/{fileId}/push	Push file to session

Requests

Method	Endpoint	Description
GET	/requests/{requestId}/status	Get async request status

Authentication

All requests require an API key:

Authorization: Bearer YOUR_API_KEY

Get your API key from portal.airtop.ai.

Error Responses

All errors follow this format:

{
  "error": {
    "code": 400,
    "message": "Invalid request body",
    "details": "..."
  }
}

Code	Meaning
400	Bad Request — invalid parameters
401	Unauthorized — invalid or missing API key
404	Not Found — resource doesn't exist or expired
422	Validation Error — request body schema mismatch
429	Rate Limited — too many requests
503	Service Unavailable — temporary capacity issue

Rate Limits

Rate limits depend on your plan. Check your current limits and usage at portal.airtop.ai.

When rate limited, wait and retry with exponential backoff.