From webflow-pack
Upgrades webflow-api SDK from v1 to v3: detects breaking changes, migrates v1-to-v2 API endpoints/auth, maps operations like sites/collections/items. Useful for Webflow integrations.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin webflow-packThis skill is limited to using the following tools:
Guide for upgrading the `webflow-api` SDK and migrating from Webflow Data API v1
Applies production Webflow API SDK patterns: singleton client, typed error handling, pagination helpers, raw responses. For integrations, refactoring, team standards.
Guides Documenso API v1 to v2 upgrades and TypeScript/Python SDK migrations with code examples and bash commands.
Initializes, builds, and deploys Webflow Cloud applications via CLI with non-interactive flags, mount path validation, and package manager detection. Use for Webflow project creation and deployment.
Share bugs, ideas, or general feedback.
Guide for upgrading the webflow-api SDK and migrating from Webflow Data API v1
to v2. Covers breaking changes, endpoint mapping, import updates, and rollback.
webflow-api SDK installed# Check installed version
npm list webflow-api
# Check latest available
npm view webflow-api version
# View changelog
npm view webflow-api --json | jq '.versions[-5:]'
| SDK Version | API Version | Node.js | Key Changes |
|---|---|---|---|
| 3.x | Data API v2 | 18+ | Current. WebflowClient, auto-retry, bulk ops |
| 2.x | Data API v1/v2 | 16+ | Transitional. Mixed v1/v2 endpoints |
| 1.x | Data API v1 | 14+ | Legacy. Webflow class, no types |
v1 endpoints deprecation: late 2026. Migrate before then.
v1: https://api.webflow.com
v2: https://api.webflow.com/v2
// v1 (old) — API key
import Webflow from "webflow-api";
const webflow = new Webflow({ token: "your-api-key" });
// v2 (current) — Access token
import { WebflowClient } from "webflow-api";
const webflow = new WebflowClient({ accessToken: "your-access-token" });
| Operation | v1 Endpoint | v2 Endpoint |
|---|---|---|
| List sites | GET /sites | GET /v2/sites |
| Get site | GET /sites/{site_id} | GET /v2/sites/{site_id} |
| Publish site | POST /sites/{site_id}/publish | POST /v2/sites/{site_id}/publish |
| List collections | GET /sites/{site_id}/collections | GET /v2/sites/{site_id}/collections |
| List items | GET /collections/{id}/items | GET /v2/collections/{id}/items |
| Create item | POST /collections/{id}/items | POST /v2/collections/{id}/items |
| Update item | PUT /collections/{id}/items/{item_id} | PATCH /v2/collections/{id}/items/{item_id} |
| List products | GET /sites/{site_id}/products | GET /v2/sites/{site_id}/products |
| List orders | GET /sites/{site_id}/orders | GET /v2/sites/{site_id}/orders |
Key v2 differences:
PATCH (not PUT) — partial updates onlyisDraft: true)/items/live)cms:read, cms:write)// ===== v1 SDK (old) =====
const webflow = new Webflow({ token: "xxx" });
// List sites
const sites = await webflow.sites();
// List collections
const collections = await webflow.collections({ siteId: "site-123" });
// Get items
const items = await webflow.items({ collectionId: "col-456" });
// Create item
const item = await webflow.createItem({
collectionId: "col-456",
fields: { name: "Test", slug: "test", _archived: false, _draft: false },
});
// Update item (full replace)
await webflow.updateItem({
collectionId: "col-456",
itemId: "item-789",
fields: { name: "Updated", slug: "test" },
});
// ===== v2 SDK (current) =====
const webflow = new WebflowClient({ accessToken: "xxx" });
// List sites
const { sites } = await webflow.sites.list();
// List collections
const { collections } = await webflow.collections.list("site-123");
// Get items (staged)
const { items } = await webflow.collections.items.listItems("col-456");
// Get items (live/published)
const { items: live } = await webflow.collections.items.listItemsLive("col-456");
// Create item (draft by default)
const item = await webflow.collections.items.createItem("col-456", {
fieldData: { name: "Test", slug: "test" },
isDraft: false,
});
// Update item (partial update via PATCH)
await webflow.collections.items.updateItem("col-456", "item-789", {
fieldData: { name: "Updated" }, // Only changed fields
});
// NEW: Bulk create (up to 100)
await webflow.collections.items.createItemsBulk("col-456", {
items: [{ fieldData: { name: "Item 1", slug: "item-1" } }],
});
// NEW: Publish items
await webflow.collections.items.publishItem("col-456", {
itemIds: ["item-789"],
});
# Create upgrade branch
git checkout -b upgrade/webflow-api-v3
# Install latest
npm install webflow-api@latest
# Run tests to find breaking changes
npm test 2>&1 | tee upgrade-test-results.txt
# Fix breaking changes (common patterns above)
# ...
# Verify in staging
npm run test:integration
# Commit and PR
git add -A
git commit -m "upgrade: webflow-api to v3 (Data API v2)"
# Rollback to previous version
npm install webflow-api@2.x.x --save-exact
# Or revert the upgrade branch
git revert HEAD
Webflow class to WebflowClient named exporttoken to accessTokenwebflow.sites() to webflow.sites.list()fieldData objectPUT to PATCH (partial)_draft/_archived to isDraft/isArchived.items property with .pagination| Issue | Cause | Solution |
|---|---|---|
TypeError: Webflow is not a constructor | Using v1 import with v3 SDK | Change to import { WebflowClient } |
400 Bad Request on create | Fields not in fieldData wrapper | Wrap fields: { fieldData: { ... } } |
405 Method Not Allowed | Using PUT instead of PATCH | Update to PATCH for item updates |
| Missing items in response | Not checking .items property | Destructure: const { items } = await ... |
For CI integration during upgrades, see webflow-ci-integration.