> ## 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.

# API Conventions

> Base URL, error format, usage periods, and OpenAPI sources.

## Base URL

```text theme={null}
https://api.floppydata.net
```

All v2 endpoints are under `/v2`.

## Authentication

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

```http theme={null}
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.

```bash theme={null}
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`.

```json theme={null}
{
  "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:

```text theme={null}
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