Cookie configurations

Use the Website Scanner REST API to create, retrieve, update, and delete cookie configurations for your website scans.

Cookie configurations let you attach cookies to scan requests so that pages behind consent gates or region selectors are scanned in the correct state. Create a configuration once and reference it by ID when you create a scan.

Get cookie config list

GET /api/v1/scanner/cookie_configs

Use this endpoint to retrieve all cookie configurations associated with your account.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  https://api-scanner.browserstack.com/api/v1/scanner/cookie_configs

Response attributes 200 application/json

Response

{
  "success": true,
  "data": {
    "cookieConfigs": [
      {
        "id": 24,
        "name": "consent_config_1",
        "domain": "example.com",
        "cookies": "consent=accepted; region=uk",
        "scanConfigCount": 3
      }
    ]
  },
  "error": null
}

Create cookie config

POST /api/v1/scanner/cookie_configs

Use this endpoint to create a new cookie configuration. After creation, reference the configuration by its ID when you create a scan.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  -X POST https://api-scanner.browserstack.com/api/v1/scanner/cookie_configs \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "consent_config_1",
    "domain": "example.com",
    "cookies": "consent=accepted; region=uk"
  }'

Response attributes 201 application/json

Response

{
  "success": true,
  "data": {
    "id": 24,
    "name": "consent_config_1",
    "domain": "example.com",
    "cookies": "consent=accepted; region=uk",
    "createdAt": "2026-10-09T10:00:00Z"
  },
  "error": null
}

Error responses 422

The API returns a 422 status code when validation fails. The following validation errors can occur:

• Name is required
• A cookie configuration named '<name>' already exists
• Domain is required
• '<domain>' is not a valid domain. Send the domain only, without https:// or a path
• Cookies are required
• Cookie '<entry>' must be in name=value format
• Duplicate cookie name '<name>'
• Cookie name '<name>' is longer than 255 characters
• Cookie '<name>' has a value longer than 4096 characters
• A configuration can hold at most 50 cookies
• An account can hold at most 200 cookie configurations

Update cookie config

PUT /api/v1/scanner/cookie_configs/{id}

Use this endpoint to update an existing cookie configuration. Only the fields you send are changed, so a cookie rotation can be a single-field request.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  -X PUT https://api-scanner.browserstack.com/api/v1/scanner/cookie_configs/24 \
  -H 'Content-Type: application/json' \
  -d '{ "cookies": "consent=accepted-v2; region=uk" }'

Response attributes 200 application/json

Response

{
  "success": true,
  "data": {
    "id": 24,
    "name": "consent_config_1",
    "domain": "example.com",
    "cookies": "consent=accepted-v2; region=uk",
    "createdAt": "2026-10-09T10:00:00Z"
  },
  "error": null
}

Error responses 404

The API returns a 404 status code if the cookie configuration ID does not exist or belongs to another account.

Error responses 422

The API returns a 422 status code when validation fails. The following validation errors can occur:

• A cookie configuration named '<name>' already exists
• '<domain>' is not a valid domain. Send the domain only, without https:// or a path
• Cookie '<entry>' must be in name=value format
• Duplicate cookie name '<name>'
• Cookie name '<name>' is longer than 255 characters
• Cookie '<name>' has a value longer than 4096 characters
• A configuration can hold at most 50 cookies

Delete cookie config

DELETE /api/v1/scanner/cookie_configs/{id}

Use this endpoint to delete a cookie configuration. Scans already using the configuration continue to run with the last known cookie values.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  -X DELETE https://api-scanner.browserstack.com/api/v1/scanner/cookie_configs/24

Response attributes 200 application/json

Response

{
  "success": true,
  "data": {
    "message": "Cookie configuration has been deleted"
  },
  "error": null
}

Error responses 404

The API returns a 404 status code if the cookie configuration ID does not exist or belongs to another account.