canonical: https://jentic.com/apis/airtop.ai/airtop

# Airtop API

Jentic publishes the only available OpenAPI specification for Airtop API, keeping it validated and agent-ready. Airtop is a cloud browser platform built for AI agents that need to operate the web with stateful sessions, persistent profiles, automations, and form filling. The 39 documented endpoints cover session lifecycle, window management, async automation creation and execution, form-filler automations, and profile saving on session termination. Authentication uses bearer tokens scoped per workspace.

## For AI agents

Spin up cloud browser sessions, run automations against live websites, save authenticated profiles, and fill forms on behalf of an AI agent.

## Scope

Does not provide LLM reasoning, native mobile automation, or local browser execution - use for cloud browser sessions, profiles, and automation execution only.

## Capabilities

- Create, list, inspect, and end browser sessions via `/v1/sessions` endpoints
- Save authenticated profiles on session termination so cookies and state persist for later runs
- Create async automations that record a sequence of actions on a target site
- Execute saved automations and form fillers against any session window
- List the windows associated with a session for multi-tab navigation
- Run form-filler automations to populate fields with structured input on behalf of an agent

## Use cases

### Stateful Cloud Browser Sessions for Agents

Provision a browser in the cloud where an AI agent can navigate, click, and authenticate without managing local Chromium. POST `/v1/sessions` creates the session, `/v1/sessions/{id}` inspects it, and DELETE `/v1/sessions/{id}` ends it. Sessions retain cookies and storage so agents can complete multi-step flows like logging in, navigating menus, and submitting forms.

Example prompt: Create a session, navigate to a target URL, perform a click on the login button, and end the session

### Profile Persistence Across Runs

Persist authenticated state by saving a session profile on termination via PUT `/v1/sessions/{sessionId}/save-profile-on-termination/{profileName}.` The next session can be launched with that profile so cookies, local storage, and logged-in state are restored - eliminating repeated login challenges and CAPTCHAs for agents.

Example prompt: Mark profile 'shopify-admin' to be saved on termination of session 'sess-123' and verify by listing profiles

### Form-Filler Automations

Run a structured form-filler automation through POST `/v1/async/sessions/{sessionId}/windows/{windowId}/fill-form` to populate web forms with fields supplied by the agent. Combined with POST `/v1/async/sessions/{sessionId}/windows/{windowId}/create-form-filler`, agents can record a form once and replay it across many submissions.

Example prompt: Run form filler 'job-application-v2' on session 'sess-123', window 'win-1' with fields { 'name': 'Pat Doe', 'email': 'pat@example.com' }

### Async Automation Recording and Execution

Record a sequence of browser interactions as an automation via POST `/v1/async/sessions/{sessionId}/windows/{windowId}/create-automation`, then replay it later with POST `/v1/async/sessions/{sessionId}/windows/{windowId}/execute-automation.` Useful for repetitive web flows such as exporting reports, checking dashboards, or scraping behind a login.

Example prompt: Create an automation that exports a CSV report from an admin dashboard and execute it weekly under a saved profile

### Agent Web Operation via Jentic

An agent that needs to operate the web searches Jentic for the right Airtop session or automation operation, loads the schema, and executes under a bearer token managed by Jentic. Combines well with form-filler operations so the agent can move through a checkout or onboarding flow without owning browser state.

Example prompt: Search Jentic for 'create a cloud browser session', load the Airtop POST `/v1/sessions` operation, and execute it to start a session for the agent's task

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/sessions` | Create a cloud browser session |
| GET | `/v1/sessions` | List active sessions |
| GET | `/v1/sessions/{id}` | Get info for a session |
| DELETE | `/v1/sessions/{id}` | End a session |
| PUT | `/v1/sessions/{sessionId}/save-profile-on-termination/{profileName}` | Save a profile on session termination |
| POST | `/v1/async/sessions/{sessionId}/windows/{windowId}/create-automation` | Create an automation |
| POST | `/v1/async/sessions/{sessionId}/windows/{windowId}/execute-automation` | Execute a saved automation |
| POST | `/v1/async/sessions/{sessionId}/windows/{windowId}/fill-form` | Run a form-filler automation |

## Key resources

- **Sessions** — Create, list, inspect, and end cloud browser sessions
- **Profiles** — Save authenticated browser profiles for reuse across sessions
- **Windows** — List and operate windows inside an active session
- **Automations** — Record and execute async automations on target windows
- **Form Fillers** — Create and run form-filler automations with structured input

## Why Jentic

- **Setup:** Wiring Airtop by hand means handling its bearer token, threading session, window, and profile ids through async automation paths, and writing your own retry logic. Through Jentic you install once, import Airtop from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Airtop puts the session and window ids in the URL path (`/sessions/{id}`, `/sessions/{sessionId}/windows/{windowId}/execute-automation`), so a rule can pin your agent to one session. You choose the operations it may call, so session deletion is only included if you add it.
- **Credential handling:** Your Airtop bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a cloud browser session' or 'fill a web form', and Jentic returns the matching Airtop operation with its session, window, and body schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Browserless** — Cloud Chromium API focused on raw automation rather than agent-shaped session and profile primitives
- **Apify** — Marketplace of pre-built scrapers and a general-purpose actor runtime
- **OpenAI API** — Pair OpenAI's reasoning with Airtop's browser to let an agent plan and act on the web

## FAQ

### Why is there no official OpenAPI spec for Airtop API?

Airtop does not publish a single canonical OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Airtop API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Airtop API use?

Airtop uses HTTP bearer tokens scoped to a workspace. Pass the token via Authorization: Bearer <token> on every call. Through Jentic the token is stored encrypted and injected at execution time so the agent never sees the raw value.

### Can I save a logged-in browser profile across sessions?

Yes. PUT `/v1/sessions/{sessionId}/save-profile-on-termination/{profileName}` marks the profile to persist when the session ends. Subsequent sessions can load that profile so cookies, storage, and login state come back without re-authenticating.

### What are the rate limits for the Airtop API?

Airtop applies per-workspace concurrency limits on active sessions plus request-rate limits on the management endpoints. Exact thresholds are documented at docs.airtop.ai. Treat HTTP 429 as a backoff signal and check workspace concurrency before creating new sessions.

### How do I create a cloud browser session through Jentic?

Install with pip install jentic, search for 'create a cloud browser session', load the Airtop POST `/v1/sessions` operation, and execute with any optional configuration (profile, locale). Jentic injects the bearer token automatically.

### Can I run a form-filler automation against a specific window?

Yes. POST `/v1/async/sessions/{sessionId}/windows/{windowId}/fill-form` runs a previously created form filler against the given window with field values supplied as structured input. Pair with /create-form-filler to record the filler once and reuse it many times.

### Can I limit what my agent is allowed to do with the Airtop API?

Yes. Because you run Jentic One yourself, you decide which Airtop operations your agent may call, so it can create and inspect sessions without ever being granted the DELETE that ends a session. Airtop carries the session and window ids in the URL path, as in `/v1/sessions/{id}` and `/v1/async/sessions/{sessionId}/windows/{windowId}/execute-automation`, so your own rules can pin the agent to a single session or window. Your bearer token stays with your instance and is injected only for the operations you have allowed.