---

name: brightdata-upgrade-migration description: 'Migrate Bright Data SDK, API, product, or response-header contracts with fixture evidence and a reversible canary. Use when upgrading the Python SDK, moving dataset endpoints, renaming Scraping Browser to Browser API, or removing legacy headers. Trigger with: "upgrade Bright Data", "migrate x-luminati headers", "change a Bright Data API contract".' allowed-tools: Read, Grep, Write, Edit, Bash(python:*) version: 2.0.0 argument-hint: "[current-to-target-contract]" model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• web-data
• bright-data
• upgrade-migration
• operations compatibility: 'Requires an approved Bright Data account or offline fixtures, current Bright Data documentation, and an authorized public-data collection purpose'

---

Bright Data Contract Migration

Overview

Inventory the exact current behavior before changing dependencies or products. Treat an SDK update, API endpoint change, Browser API rename, and product migration as separate changes with separate rollback boundaries.

Prerequisites

• A pinned current dependency or configuration and documented target contract
• Golden synthetic fixtures plus representative redacted receipts
• A dual-read or feature-flag path and rollback owner

Instructions

Step 1: Build the delta

Read the lockfile, adapter, and runbooks; Grep for x-luminati, old product names, obsolete endpoints, raw vendor response coupling, and undocumented ports.

Step 2: Update one boundary

Write the target dependency, API, or header mapping. Current diagnostics use Proxy-Status and x-brd-*; Browser API replaces the former Scraping Browser name. Do not invent version transitions.

Step 3: Verify compatibility

Edit fixture tests for success, authentication, policy, throttle, lifecycle, schema, and delivery states. Use Bash(python:*) for the pinned type and test suite and compare normalized outputs.

Step 4: Canary and retire

Run an authorized feature-flag canary, compare data and operational receipts, then remove the old path only after rollback expiry and owner signoff.

Tool Discipline

Use Read and Grep for the migration inventory. Use Write and Edit for dependency, adapter, fixture, and runbook changes. Use Bash(python:*) for local tests; it does not authorize live migration traffic or credential changes.

Output

• Current-to-target contract matrix
• Passing old and new fixture comparison and canary receipt
• Rollback path plus explicit old-contract retirement decision

Examples

First replace parsing of x-luminati-error with current x-brd-error and Proxy-Status fixtures. Keep a short dual-read window for retained historical receipts, but require current fields from new live responses.

Error Handling

Failure	Meaning	Response
Migration combines product and SDK changes	Failure attribution is impossible	Split the rollout into independently reversible steps
Golden fixture contains live data	Test evidence is unsafe	Replace it with a synthetic contract fixture
New path changes normalized output	Downstream behavior would drift	Hold promotion and reconcile the schema

Resources

• Python SDK
• Proxy error catalog
• Browser API
• Web Scraper API asynchronous requests