DOCSEARCHbyAlgolia
Submit Docs

Webflow JavaScript/TypeScript SDK

repository·master·Indexed 43 days ago

https://github.com/webflow/js-webflow-api

A type-safe, programmatic interface to the Webflow Data API (version 3.3.5) for managing sites, domains, CMS collections, and pages. The SDK includes the WebflowClient for API calls, support for Workspace and Site tokens, OAuth authentication, and bulk CMS item management.

Tokens
42.2K
Snippets
157
Records
175
Agent score
53%

What's inside Webflow

  1. Authenticate with a Workspace or Site token

    master

    For simple access, you can use a static token.

    • Workspace Token: Provides access to all sites in your Webflow Workspace. Generate this in the Webflow Dashboard under Apps & Integrations > Manage > Workspace API access.
    • Site Token: Provides access to a single specific site. Generate this in the site settings under API access.
    import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN,
});

  2. Manage Live (Published) Items

    master

    The SDK provides specific methods to interact with items that are currently published on the live site.

    List Published Items

    Use listItemsLive() to list all published items in a collection. For high-volume real-time reads, consider using the Content Delivery API at api-cdn.webflow.com. Required scope: CMS:read

    Create Published Items

    Use createItemLive() to create an item that is immediately published to the live site. Required scope: CMS:write

    Update Published Items

    Use updateItemsLive() to update up to 100 published items. Updates are applied to the live site immediately. Required scope: CMS:write

    Unpublish Items

    Use deleteItemsLive() to unpublish up to 100 items from the live site (sets isDraft to true). Use deleteItemLive() for a single item. Required scope: CMS:write

    Get Published Item Details

    Use getItemLive() to get details of a specific live item. Required scope: CMS:read

    // Example: Unpublishing a live item
await client.collections.items.deleteItemLive("580e63fc8c9a982ac9b8b745", "580e64008c9a982ac9b8b754", {
    cmsLocaleId: "cmsLocaleId"
});

  3. Use the WebflowClient for API calls

    master

    Import WebflowClient, instantiate it with an accessToken, and use the generated resource methods (like sites) to interact with the Webflow Data API.

    import { WebflowClient } from "webflow-api";

// Initialize client
const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN,
});

const site_id = "639656400769508adc12fe42";

// List all sites
const sites = await webflow.sites.list();

// Get a specific site
const site = await webflow.sites.get(site_id);

// Get custom domains for a site
const customDomains = await webflow.sites.getCustomDomain(site_id);

// Publish a site
const publishRequest = await webflow.sites.publish(site_id, {
  customDomains: ["domain_id_1", "domain_id_2"],
  publishToWebflowSubdomain: true,
});

  4. Migrate bulk CMS Item creation to v3

    master

    In v3.0.0, creating CMS items across multiple locales is handled by the unified client.collections.items.createItems() method.

    • Removed: client.collections.createItemForMultipleLocales().
    • New Pattern: Use client.collections.items.createItems() and provide the cmsLocaleIds array within the options object.
    const newItems = client.collections.items.createItems(collectionId, {
    cmsLocaleIds: [primaryCmsLocaleId, secondaryCmsLocaleId],
    isArchived: false,
    isDraft: false,
    fieldData: {
        name: "My Item For Multiple Locales",
        slug: "my-item",
        "plain-text": "foo",
    },
});

  5. Implement OAuth authentication

    master

    To implement OAuth, you must first register a Webflow App in your Workspace with the "Data Client" building block to obtain a clientId and clientSecret.

    Step 1: Generate an authorization URL

    Use WebflowClient.authorizeURL to create the URL you will redirect users to for permission approval.

    Step 2: Retrieve an access token

    After the user approves, capture the code from the callback and exchange it for an access token using WebflowClient.getAccessToken.

    Step 3: Instantiate the client

    Use the retrieved accessToken to create a new WebflowClient instance.

    import { WebflowClient } from "webflow-api";

// 1. Generate URL
const authorizeUrl = WebflowClient.authorizeURL({
    state: "your_state",
    scope: "sites:read",
    clientId: "your_client_id",
    redirectUri: "your_redirect_uri",
});

// 2. Exchange code for token
const accessToken = await WebflowClient.getAccessToken({
  clientId: "your_client_id",
  clientSecret: "your_client_secret",
  code: "your_authorization_code"
});

// 3. Use the token
const webflow = new WebflowClient({ accessToken });
const { sites } = await webflow.sites.list();

  6. Migrate CMS Collection deletion from v2 to v3

    master

    In v3.0.0, the method for deleting a Collection has changed to avoid collision with field deletion.

    • To delete a Collection: Use client.collections.delete(collectionId).
    • To delete a Collection field: Use client.collections.fields.delete(collectionId, fieldId).
    • Removed: client.collections.deleteCollection() is no longer available.
    // v3.0.0 way to delete a collection
client.collections.delete(collectionId);

// v3.0.0 way to delete a field
client.collections.fields.delete(collectionId, fieldId);

  9. Manage Webflow sites with SitesClient

    master

    The SitesClient class provides methods to manage sites within a Webflow workspace. It acts as a gateway to various sub-resources related to sites, such as redirects, plans, forms, and scripts.

    Sub-resources available via SitesClient:

    • redirects: RedirectsClient
    • plans: PlansClient
    • robotsTxt: RobotsTxtClient
    • wellKnown: WellKnownClient
    • activityLogs: ActivityLogsClient
    • comments: CommentsClient
    • scripts: ScriptsClient
    • forms: FormsClient
    import { Webflow } from 'webflow';

// Assuming 'client' is an instantiated Webflow client
const siteRedirects = client.sites.redirects;
const siteForms = client.sites.forms;

  10. OrdersClient configuration and request options

    master

    The OrdersClient uses two types of configuration objects:

    1. OrdersClient.Options: Passed during client instantiation to configure global settings like authentication and base URL.
    2. OrdersClient.RequestOptions: Passed to individual method calls to override settings for a specific request (e.g., headers, queryParams, timeoutInSeconds, maxRetries, or abortSignal).

  11. Manage CMS Collections with CollectionsClient

    master

    The CollectionsClient is used to manage CMS collections within a Webflow site. It provides methods to list, create, retrieve, and delete collections. It also provides access to sub-clients for managing collection fields and items.

    Sub-clients:

    • client.collections.fields: Access the FieldsClient to manage fields within collections.
    • client.collections.items: Access the ItemsClient to manage items within collections.
    import Webflow from '@webflow/webflow-sdk';

// Accessing collections and sub-clients
const collections = client.collections;
const fields = client.collections.fields;
const items = client.collections.items;