Webflow Data API SDK

Installation

Using npm:

$ npm install webflow-api

Using yarn

$ yarn add webflow-api

Usage

The constructor takes in a few optional parameters to initialize the API client

• token - the access token to use
• headers - additional headers to add to the request
• version - the version of the API you wish to use

constWebflow=require("webflow-api");// initialize the client with the access tokenconstwebflow=newWebflow({token: "[ACCESS TOKEN]"});// fully loadedconstwebflow=newWebflow({token: "[ACCESS TOKEN]",version: "1.0.0",headers: {"User-Agent": "My Webflow App / 1.0",},});

Transitioning to API v2

We're actively working on a new version of the SDK that will fully support API v2. In the meantime, to make use of API v2 with our SDK, there are some important changes you need to be aware of:

Setting Up For API v2

When initializing your client, it's crucial to set the beta flag to true in the client options. This ensures you're targeting the API v2 endpoints.

constwebflow=newWebflow({beta: true, ...otherOptions});

Please note, when the beta flag is set, several built-in methods will not be available. These methods include, but are not limited to, info, authenticatedUser, sites, site, etc. Attempting to use these will throw an error.

Calling API v2 Endpoints

To interact with API v2, you'll need to move away from using built-in methods, and instead use the provided HTTP methods directly.

For instance, where you previously used sites():

// get the first siteconst[site]=awaitwebflow.sites();

For API v2, you will need to use direct HTTP methods:

// get the first siteconstsites=awaitwebflow.get("/sites");constsite=sites[0];

We understand that this is a shift in how you interact with the SDK, but rest assured, our upcoming SDK version will streamline this process and offer a more integrated experience with API v2.

Basic Usage

Chaining Calls

You can retrieve child resources by chaining calls on the parent object.

// get the first siteconst[site]=awaitwebflow.sites();// get the first collection in the siteconst[collection]=awaitsite.collections();// get the first item in the collectionconst[item]=awaitcollection.items();// get one item from the collectionconstitem=awaitcollection.items({itemId: "[ITEM ID]"});

Pagination

To paginate results, pass in the limit and offset options.

// Get the first page of resultsconstpage1=awaitcollection.items({limit: 20});// Get the second page of resultsconstpage2=awaitcollection.items({limit: 20,offset: 20});

Rate Limit

Check rate limit status on each call by checking the _meta property.

// make an api callconstsite=awaitwebflow.site({siteId: "[SITE ID]"});// check rate limitconst{ rateLimit }=site._meta;// { limit: 60, remaining: 56 }

Update Token

If you need to update the access token, you can set the token property at any time.

// token is unsetconstwebflow=newWebflow();// set tokenwebflow.token="[ACCESS TOKEN]";// remove the tokenwebflow.clearToken();

Calling APIs Directly

All Webflow API endpoints can be called directly using the get, post, put, and delete methods.

// call the sites endpoint directlyconstsites=awaitwebflow.get("/sites");// post to an endpoint directlyconstresult=awaitwebflow.post("/sites/[SITE ID]/publish",{domains: ["hello-webflow.com"],});

OAuth

To implement OAuth, you'll need a Webflow App registered and a webserver running, that is publicly facing.

Authorize

The first step in OAuth is to generate an authorization url to redirect the user to.

// Get the authorization url to redirect users toconsturl=webflow.authorizeUrl({client_id: "[CLIENT ID]",state: "1234567890",// optionalredirect_uri: "https://my.server.com/oauth/callback",// optional});// redirect user from your server routeres.redirect(url);

Using the scopes Parameter with v2 API

The v2 API introduces the concept of 'scopes', providing more control over app permissions. Instead of using the scope parameter as a single string, you can define multiple permissions using the scopes array:

consturl=webflow.authorizeUrl({client_id: "[CLIENT ID]",redirect_uri: "https://my.server.com/oauth/callback",scopes: ["read:sites","write:items","read:users"],});

For more information and a detailed list of available scopes, refer to our Scopes Guide.

Access Token

Once a user has authorized their Webflow resource(s), Webflow will redirect back to your server with a code. Use this to get an access token.

constauth=awaitwebflow.accessToken({
client_id,
client_secret,
code,
redirect_uri,// optional - required if used in the authorize step});// you now have the user's access token to make API requests withconstuserWF=newWebflow({token: auth.access_token});// pull information for the userconstauthenticatedUser=awaituserWF.authenticatedUser();

Revoke Token

If the user decides to disconnect from your server, you should call revoke token to remove the authorization.

constresult=awaitwebflow.revokeToken({
client_id,
client_secret,
access_token,});// ensure it went throughresult.didRevoke===true;

Examples

Sites

Get all sites available or lookup by site id.

// List all sitesconstsites=awaitwebflow.sites();// Get a single siteconstsite=awaitwebflow.site({siteId: "[SITE ID]"});

Collections

Get all collections available for a site or lookup by collection id.

// Get a site's collection from the siteconstcollections=awaitsite.collections();// Get a site's collection by passing in a site idconstcollections=awaitwebflow.collections({siteId: "[SITE ID]"});// Get a single collectionconstcollection=awaitwebflow.collection({collectionId: "[COLLECTION ID]"});

Collection Items

Get all collection items available for a collection or lookup by item id.

// Get the items from a collectionconstitems=awaitcollection.items();// Get a subset of itemsconstitems=awaitcollection.items({limit: 10,offset: 2});// Get a single itemconstitem=awaitwebflow.item({collectionId: "[COLLECTION ID]",itemId: "[ITEM ID]"});

Update an Item

// Set the fields to updateconstfields={name: "New Name",_archived: false,_draft: false,slug: "new-name",};// call updateconstupdatedItem=awaitwebflow.updateItem({collectionId: "[COLLECTION ID]",itemId: "[ITEM ID]",
fields,});

Memberships

// Get a site's users from the siteconstusers=awaitsite.users();// Get a site's users with a site idconstusers=awaitwebflow.users({siteId: "[SITE ID]",});// Get a single userconstuser=awaitsite.user({siteId: "[SITE ID]",userId: "[USER ID]",});// Get a site's access groupsconstaccessGroups=awaitsite.accessGroups();// Get a site's access groups with a site idconstaccessGroups=awaitwebflow.accessGroups({siteId: "[SITE ID]",});

Webhooks

// get webhooks for a siteconstwebhooks=awaitsite.webhooks();// create a webhookconstwebhook=awaitsite.createWebhook({triggerType: "form_submission",url: "https://webhook.site",});

Authenticated User

// pull information for the authenticated userconstauthenticatedUser=awaitwebflow.authenticatedUser();

Contributing

Contributions are welcome - feel free to open an issue or pull request.

License

The MIT license - see LICENSE.