> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airtop.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airtop.ai/_mcp/server.

# Create a session

POST https://api.airtop.ai/api/v1/sessions
Content-Type: application/json

Reference: https://docs.airtop.ai/api-reference/airtop-api/sessions/create

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `configuration` (SessionConfigV1, optional) — Session configuration

## Response

### 201

Created

- `data` (ExternalSessionWithConnectionInfo, required)
- `meta` (EnvelopeDefaultMeta, required)
- `errors` (list of Issue, optional)
- `warnings` (list of Issue, optional)

## Types

### SessionConfigV1

- `extensionIds` (list of string, optional) — Google Web Store extension IDs to be loaded into the session.
- `profileName` (string, optional) — Name of a profile to load into the session.
- `proxy` (SessionConfigV1Proxy, optional) — Proxy configuration.
- `record` (boolean, optional) — Enable session recording.
- `solveCaptcha` (boolean, optional) — Automatically solve captcha challenges.
- `timeoutMinutes` (integer, optional, default: 10) — Number of minutes of inactivity (idle timeout) after which the session will terminate. The idle timeout is reset when a user makes an incoming HTTP request, AI request, or new WebSocket connection to the session. Thus, when using drivers like Puppeteer, Selenium or Playwright, the timeout reset depends on the nature of the driver request. If not specified, defaults to 10 minutes.
- `baseProfileId` (string, optional, deprecated) — Deprecated: Use profileName instead.
- `persistProfile` (boolean, optional, deprecated) — Deprecated: use Save Profile On Termination API instead.

### ExternalSessionWithConnectionInfo

- `configuration` (ExternalSessionConfig, required) — Session configuration details. DEPRECATED
- `id` (string, required) — Id of the session.
- `status` (string, required) — Session status.
- `cdpUrl` (string, optional) — Url to connect to chrome devtools protocol port on the Airtop browser. Include the header 'Authorization: Bearer \<api-key>.'
- `cdpWsUrl` (string, optional) — Websocket url to connect to the Airtop browser for CDP-based automation frameworks (e.g. Puppeteer or Playwright). Include the header 'Authorization: Bearer \<airtop-api-key>.'
- `chromedriverUrl` (string, optional) — Websocket url to connect to the Airtop browser for webdriver-based automation frameworks (e.g. Selenium). Include the header 'Authorization: Bearer \<airtop-api-key>.'
- `currentUsage` (long, optional) — Current usage in minutes.
- `dateCreated` (datetime, optional) — Date the session was created.
- `lastActivity` (datetime, optional) — Date of the last activity.
- `viceUrl` (string, optional) — -
- `profileId` (string, optional, deprecated) — Id of a newly persisted profile. DEPRECATED: Use profileName.

### EnvelopeDefaultMeta

- `requestId` (string, optional)

### Issue

- `message` (string, required) — Message describing the issue.
- `code` (string, optional) — Issue code.
- `details` (map from string to any, optional) — Any associated details.
- `reason` (string, optional) — Underlying reason for the issue.

### SessionConfigV1Proxy

Proxy configuration.

### ExternalSessionConfig

- `baseProfileId` (string, optional) — Id of a profile to load into the session.
- `persistProfile` (boolean, optional) — Persist the profile.
- `timeoutMinutes` (integer, optional, default: 10) — Max length of session in minutes, after which it will terminate if not already deleted.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "data": {
    "configuration": {
      "baseProfileId": "a13c6f73-bd89-4a76-ab32-5a6c422e8224",
      "persistProfile": true,
      "timeoutMinutes": 10
    },
    "id": "6aac6f73-bd89-4a76-ab32-5a6c422e8b0b",
    "status": "active",
    "cdpUrl": "cdpUrl",
    "cdpWsUrl": "cdpWsUrl",
    "chromedriverUrl": "chromedriverUrl",
    "currentUsage": 1000000,
    "dateCreated": "2024-01-15T09:30:00Z",
    "lastActivity": "2024-01-15T09:30:00Z",
    "viceUrl": "viceUrl",
    "profileId": "427c6f73-bd89-4a76-ab32-5a6c422e8b0b"
  },
  "meta": {
    "requestId": "requestId"
  },
  "errors": [
    {
      "message": "message",
      "code": "code",
      "details": {
        "key": "value"
      },
      "reason": "reason"
    }
  ],
  "warnings": [
    {
      "message": "message",
      "code": "code",
      "details": {
        "key": "value"
      },
      "reason": "reason"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.airtop.ai/api/v1/sessions"

payload = {}
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```typescript
import { AirtopClient } from "@airtop/sdk";

const client = new AirtopClient({ apiKey: "YOUR_API_KEY" });
await client.sessions.create();

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.airtop.ai/api/v1/sessions"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.airtop.ai/api/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.airtop.ai/api/v1/sessions")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.airtop.ai/api/v1/sessions', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.airtop.ai/api/v1/sessions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.airtop.ai/api/v1/sessions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```