API Conventions - Floppydata Client API

Base URL

https://api.floppydata.net

All v2 endpoints are under /v2.

Authentication

Pass your Client API key in X-Api-Key.

X-Api-Key: YOUR_API_KEY

Dates and Usage Periods

Usage endpoints return UTC rollups:

Field	Meaning
`yesterday`	Previous UTC calendar day
`last7Days`	Rolling UTC window ending at request time
`last30Days`	Rolling UTC window ending at request time
`requestedRange`	Included only when `from` or `to` is provided
`lastUpdatedAt`	Latest usage data timestamp, or `null`

Date filters use RFC 3339 date or datetime strings.

curl --request GET \
  --url "https://api.floppydata.net/v2/account/usage?from=2026-03-01&to=2026-03-12" \
  --header "X-Api-Key: YOUR_API_KEY"

Errors

v2 errors use a JSON object with code, message, and details.

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters.",
    "details": {}
  }
}

Common codes include unauthorized, forbidden, invalid_request, insufficient_balance, account_not_configured, not_found, upstream_error, and internal_error. Cloud Browser operations can also return settings_in_use, settings_limit_reached, session_not_active, and connection_in_use. When present, use details.target, details.recoveryHint, details.activeSessionId, and details.nextOperationId to decide what to fix or call next. Include details.requestId when contacting support about an upstream or internal failure.

Cloud Browser WebSocket Connections

Create or get an active browser session, then pass its signed connectUrl directly to Playwright or Puppeteer. The WebSocket relay does not use the X-Api-Key header and permits one active connection per session. If the connection token is invalid or expired, get the active session again for a fresh connectUrl. If keepAlive is true, a disconnected session can reconnect until expiresAt; otherwise closing the relay stops the session.

OpenAPI

The current v2 OpenAPI source is available at:

https://api.floppydata.net/v2/openapi.json

This docs repository keeps:

api-reference/openapi.json for v2
api-reference/openapi-v1.json for legacy v1

​Base URL

​Authentication

​Dates and Usage Periods

​Errors

​Cloud Browser WebSocket Connections

​OpenAPI