> ## Documentation Index
> Fetch the complete documentation index at: https://floppydata.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Session
> Creates and starts a browser. The smallest request is {}. Connect with the returned WebSocket URL, then navigate with Playwright or Puppeteer. Reuse settings.id to restore the saved identity and browser state.
The smallest request is `{}`. The response includes a signed `connectUrl` and an opaque `settings.id`; connect first, then navigate with Playwright or Puppeteer. The API does not accept `startUrl`.
Create, connect, navigate, reuse settings, and stop a browser safely.
## OpenAPI
````yaml api-reference/openapi.json POST /v2/browser/sessions
openapi: 3.1.0
info:
title: Floppydata Client API
description: >-
Client API v2 for Web Data, proxy products, proxy tools, and account
rollups. You can manage your API keys in [API
keys](https://app.floppydata.com/api-keys).
version: 2.0.0
servers:
- url: https://api.floppydata.net
description: Production
security:
- apiKeyHeader: []
tags:
- name: Web Data
description: Fetch pages and inspect Web Data balance and usage.
- name: Proxy
description: Proxy tools shared across proxy products.
- name: Rotating Proxy
description: Rotating proxy subusers, connections, locations, balance, and usage.
- name: Static Proxy
description: Static proxy inventory for the authenticated account.
- name: Account
description: Account-level balance and usage rollups across available products.
- name: Cloud Browser
description: |-
Session-first cloud browsers with persistent settings under the hood.
Create a session, connect using the returned WebSocket URL, then navigate with Playwright or Puppeteer. Reuse settings.id to restore the same identity and browser state.
paths:
/v2/browser/sessions:
post:
tags:
- Cloud Browser
summary: Create a browser session
description: >-
Creates and starts a browser. The smallest request is {}. Connect with
the returned WebSocket URL, then navigate with Playwright or Puppeteer.
Reuse settings.id to restore the saved identity and browser state.
operationId: createBrowserSession
requestBody:
content:
application/json:
schema:
type: object
properties:
settings:
type: object
properties:
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required:
- id
additionalProperties: false
browser:
type: object
properties:
viewport:
type: object
properties:
width:
type: integer
minimum: 320
maximum: 7680
height:
type: integer
minimum: 240
maximum: 4320
required:
- width
- height
additionalProperties: false
fingerprint:
type: object
properties:
strategy:
default: auto
type: string
enum:
- auto
- custom
os:
type: string
enum:
- linux
- windows
- macos
- android
osVersion:
type: string
minLength: 1
maxLength: 64
userAgent:
type: string
minLength: 1
maxLength: 1024
screen:
type: object
properties:
width:
type: integer
minimum: 320
maximum: 7680
height:
type: integer
minimum: 240
maximum: 4320
devicePixelRatio:
type: number
minimum: 0.5
maximum: 8
required:
- width
- height
additionalProperties: false
locale:
type: string
minLength: 2
maxLength: 64
pattern: ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$
timezone:
anyOf:
- type: string
const: auto
- type: string
maxLength: 64
pattern: ^[A-Za-z_+-]+(?:\/[A-Za-z0-9_+.-]+)+$
geolocation:
type: object
properties:
mode:
type: string
enum:
- auto
- custom
- disabled
latitude:
type: number
minimum: -90
maximum: 90
longitude:
type: number
minimum: -180
maximum: 180
accuracy:
type: number
exclusiveMinimum: 0
maximum: 100000
required:
- mode
additionalProperties: false
hardware:
type: object
properties:
cpuCores:
type: integer
minimum: 1
maximum: 128
memoryGb:
type: integer
minimum: 1
maximum: 256
maxTouchPoints:
type: integer
minimum: 0
maximum: 20
additionalProperties: false
masking:
type: object
properties:
canvas:
type: string
enum:
- auto
- noise
- 'off'
webgl:
type: object
properties:
mode:
type: string
enum:
- auto
- noise
- mask
- 'off'
vendor:
type: string
minLength: 1
maxLength: 256
renderer:
type: string
minLength: 1
maxLength: 512
additionalProperties: false
audioContext:
type: string
enum:
- auto
- noise
- 'off'
clientRects:
type: string
enum:
- auto
- noise
- 'off'
webrtc:
type: string
enum:
- auto
- proxy
- disabled
mediaDevices:
type: object
properties:
mode:
type: string
enum:
- auto
- mask
- disabled
videoInputs:
type: integer
minimum: 0
maximum: 20
audioInputs:
type: integer
minimum: 0
maximum: 20
audioOutputs:
type: integer
minimum: 0
maximum: 20
additionalProperties: false
fonts:
type: object
properties:
mode:
type: string
enum:
- auto
- custom
families:
maxItems: 256
type: array
items:
type: string
minLength: 1
maxLength: 128
additionalProperties: false
additionalProperties: false
additionalProperties: false
additionalProperties: false
storage:
type: object
properties:
cookies:
type: object
properties:
mode:
default: merge
type: string
enum:
- merge
- replace
items:
maxItems: 100
type: array
items:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 256
value:
type: string
maxLength: 16384
url:
type: string
maxLength: 2048
format: uri
domain:
type: string
minLength: 1
maxLength: 253
path:
type: string
minLength: 1
maxLength: 2048
expires:
type: integer
minimum: 0
maximum: 9007199254740991
httpOnly:
type: boolean
secure:
type: boolean
sameSite:
type: string
enum:
- strict
- lax
- none
required:
- name
- value
additionalProperties: false
required:
- items
additionalProperties: false
additionalProperties: false
proxy:
type: object
properties:
type:
default: residential
type: string
enum:
- residential
- mobile
- datacenter
location:
type: object
properties:
countryCode:
type: string
minLength: 2
maxLength: 2
pattern: ^[A-Za-z]{2}$
state:
type: string
minLength: 1
maxLength: 128
city:
type: string
minLength: 1
maxLength: 128
additionalProperties: false
asn:
type: string
maxLength: 32
pattern: ^\d+$
rotation:
type: object
properties:
mode:
default: sticky
type: string
enum:
- sticky
- perRequest
- interval
intervalMinutes:
anyOf:
- type: number
const: 5
- type: number
const: 10
- type: number
const: 15
- type: number
const: 20
- type: number
const: 60
stickyKey:
type: string
minLength: 1
maxLength: 128
additionalProperties: false
additionalProperties: false
runtime:
default:
timeoutSeconds: 600
keepAlive: false
type: object
properties:
timeoutSeconds:
default: 600
type: integer
minimum: 60
maximum: 21600
keepAlive:
default: false
type: boolean
additionalProperties: false
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
additionalProperties: false
description: >-
Session-first browser request. Every field is optional; connect
and navigate after creation.
responses:
'201':
description: Browser session started.
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
status:
type: string
enum:
- running
- stopped
- timedOut
- failed
connectUrl:
anyOf:
- type: string
- type: 'null'
settings:
type: object
properties:
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required:
- id
additionalProperties: false
runtime:
type: object
properties:
timeoutSeconds:
default: 600
type: integer
minimum: 60
maximum: 21600
keepAlive:
default: false
type: boolean
additionalProperties: false
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
createdAt:
type: string
startedAt:
anyOf:
- type: string
- type: 'null'
expiresAt:
type: string
endedAt:
anyOf:
- type: string
- type: 'null'
required:
- id
- status
- connectUrl
- settings
- runtime
- createdAt
- startedAt
- expiresAt
- endedAt
additionalProperties: false
example:
id: 58e531ee-16ca-49d0-8722-b425d154cc10
status: running
connectUrl: >-
wss://api.floppydata.net/v2/browser/sessions/58e531ee-16ca-49d0-8722-b425d154cc10/connect?token=SIGNED_TOKEN
settings:
id: f742823c-7ba6-4488-a72d-6e9c5447eacb
runtime:
timeoutSeconds: 1800
keepAlive: true
metadata:
taskId: checkout-42
createdAt: '2026-07-10T12:00:00Z'
startedAt: '2026-07-10T12:00:01Z'
expiresAt: '2026-07-10T12:30:00Z'
endedAt: null
'400':
description: The request body or query parameters are invalid.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: invalid_request
message: Invalid request parameters.
details:
issues:
- path: country
code: invalid_format
message: Expected a 2-letter country code.
'401':
description: The API key is missing, invalid, or expired.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: unauthorized
message: Unauthorized
details: {}
'402':
description: The account does not have enough balance for this request.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: insufficient_balance
message: Insufficient proxy traffic balance.
details: {}
'403':
description: The API key does not grant access to this operation.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: forbidden
message: Forbidden
details: {}
'404':
description: The requested resource is not available.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: not_found
message: Rotating proxy credential was not found.
details: {}
'409':
description: The authenticated account is not configured for this product.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: account_not_configured
message: Account is not configured for proxy products.
details: {}
'500':
description: An unexpected server error occurred.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: internal_error
message: Internal Server Error
details: {}
'502':
description: An upstream service failed while processing the request.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: upstream_error
message: Failed to fetch data from an upstream service.
details:
upstreamStatus: 503
components:
securitySchemes:
apiKeyHeader:
type: apiKey
in: header
name: X-Api-Key
description: Client API key for the authenticated account.
````