Webflow setup

The Webflow connector creates staged CMS items, flagged as drafts, in a collection you choose. Nothing reaches your live site until you press Publish in Webflow yourself.

Step 1 - create a Site API token

1. Open your site in Webflow and click the gear icon (Site settings).

2. Go to Apps & integrations, scroll to API access, and click Generate API token.

3. Name it BirchSeek and tick three scopes:

   Scope	Why
   cms:read	Reading the collection schema and finding our prior item
   cms:write	Creating and updating collection items
   sites:read	Confirming which site the token belongs to (optional)

4. Click Generate token and copy it. Webflow shows it once.

Two Webflow rules worth knowing up front: only site admins can create tokens, and a site can hold at most 5 of them. Tokens also expire after 365 consecutive days of inactivity — BirchSeek’s refresh runs keep yours warm in practice, but if you pause a project for a year you will need a new one.

Step 2 - map your collection’s fields

This is the part unique to Webflow, and it is worth ten careful minutes. Every field slug except Name and Slug is defined by you when you build the collection, so there is no universal “body” field for BirchSeek to guess at.

Setting	Required	Notes
Collection	yes	The blog collection to write into
Body field	yes	Must be a Rich text field — this receives the article
Summary field	no	Plain text or rich text; receives the meta description
Meta title field	no	Plain text
Publish date field	no	Must be a Date field
Author field	no	Plain text (reference-typed author fields are not supported)
Tags field	no	Plain text; tags are comma-joined
Canonical field	no	Advanced — read the caveat below before using it
Ownership field	no	Strongly recommended: see step 3
Extra fields	no	Constant values for any other required field on the collection

Two mapping rules the connection test enforces:

• No two roles may point at the same field. One field holds one value, so the second would silently overwrite the first — mapping the summary onto your body field would replace the whole article with a one-sentence meta description, and Webflow would answer 202 Accepted. BirchSeek refuses to save that config rather than let it happen quietly.
• Every required field needs a value. If your collection has a required field BirchSeek has nothing to put in — a category reference, a switch, a cover image — give it a constant under Extra fields. Otherwise every publish fails with a Webflow 400, and the connection test tells you which field up front.

Step 3 - add an ownership field

This one takes two minutes and is the difference between an article that publishes and an article that stops.

A Webflow collection item carries no metadata. Every field on it is one you defined, so there is nowhere for BirchSeek to leave a private note saying “I wrote this”. That matters because the only other handle on an item is its slug, and a slug is a string you can type into any item in the collection, including a page you wrote yourself. Adopting a slug match would mean PATCHing a generated article over your page, and BirchSeek will not do that.

So give it a field to sign its work with:

1. In the Designer, open your blog collection and add a Plain text field. Call it whatever you like; BirchSeek ID is fine.
2. Leave it out of the collection page template. Nothing binds to it, so no reader ever sees it.
3. Put its slug (birchseek-id) in the connector’s Ownership field and re-test.

BirchSeek then writes the article’s id into that field on every create and every update, so items published before you mapped it get signed the next time they refresh. The connection test checks the field exists and is Plain text, so a broken mapping is a failed test rather than a failed publish.

What happens if you skip it. BirchSeek still publishes, and still refreshes its own articles, by addressing the item id its last publish returned. But that is the only handle it has. If the id is ever lost, or an item already holds the slug this article wants, it refuses the item it found by slug rather than risk replacing your page. And because Webflow rejects duplicate slugs instead of uniquifying them, it cannot create a second item either. That article’s publish stops there, with a message naming both repairs: delete or rename the colliding item, or map an ownership field. The connection test warns you about this before any of it happens.

Step 4 - send a test

Send a test calls GET /v2/collections/{id}, which proves the token, the cms:read scope, and the collection all at once. It then checks your mapping against the collection’s real schema and reports every problem in one message, so you fix the form once instead of five times.

What BirchSeek writes

Per article, via POST /v2/collections/{id}/items — the staged endpoint, always:

• fieldData.name and fieldData.slug from the article title and slug
• your body field, as HTML rendered from the article
• whichever optional fields you mapped
• your ownership field, if you mapped one, holding the article’s id
• isDraft: true (configurable) and isArchived: false

Your body field ends with a ## Sources block: a numbered list pairing each verified claim with the page it was checked against, rendered into the HTML like any other section. BirchSeek composes that body once, before any connector sees it, so every connector publishing to your own site writes the same block - there is nothing to append yourself. (A syndicated copy to dev.to, Hashnode or Medium carries the same block, and the canonical link back to your page besides. That copy is not covered by the project setting: those three platforms have no citation field of their own, so the body is the only place the evidence can travel.) The block is on by default, and there is no switch for it in the dashboard: it is a project setting called append_sources_section, and the only way to change it today is PATCH /v1/projects/{id} carrying the whole settings object, because that request replaces the object rather than merging into it.

On a refresh run the same item is updated in place via PATCH, and the draft/archived flags are deliberately not sent — so an item you already reviewed and un-drafted stays that way.

Caveats worth reading before you connect

• Code blocks are dropped. Webflow’s own documentation states that code blocks in Rich Text fields are not supported through the API. If your articles include fenced code, that content will not survive. Tables are unreliable for the same reason: Webflow sanitises rich-text HTML server-side and reports nothing when it strips something.
• Canonical URLs need setup on your side. Webflow has no per-item canonical field, and its Data API cannot set one. Every Collection Page already emits a correct self-canonical, which is the right default. If you want to override it, you must first add a plain-text field to the collection and bind it to a <link rel="canonical"> HTML embed in the collection page template in the Designer. Only then does mapping Canonical field do anything — writing to a field nobody bound produces a canonical that does not exist.
• BirchSeek never reports a live URL for Webflow. Items are staged, so they are not on your site until you republish it. The optional Public URL template renders a prediction in the connection test so you can sanity-check the shape, but it is never handed onward as the article’s canonical.

Troubleshooting

• 401 not_authorized - the token was revoked, or it hit the 365-day inactivity expiry. Generate a new one.
• 403 forbidden - the token exists but lacks cms:write. Scopes cannot be edited after creation; generate a new token with the right ones.
• 404 resource_not_found - the collection id is wrong, or the collection was deleted.
• “republish your Webflow site” - Webflow reserves a deleted item’s slug until the site is republished, so a create can collide with a slug that no longer appears anywhere. Publish your site in Webflow, then retry.
• “already exists in this collection and was not created by birchseek” - an item you wrote is sitting on the slug this article wants. Nothing was written. Rename that item’s slug, or delete it, or give the article a different slug, then publish again.
• “no owner_field is mapped, so nothing on the item records who wrote it” - the same collision, with no ownership field to settle it. The item may well be BirchSeek’s; nothing on it can show that, so it is left alone. Clear the collision as above, and map an Ownership field (step 3) so the next one resolves itself.
• “already belongs to birchseek article …” - two of your articles have been given the same slug. One collection item cannot serve both: whichever refreshed last would overwrite the other. Change one article’s slug.
• 429 - Webflow allows 60 requests/minute on Starter and Basic plans, 120 on CMS and above. One article costs 2-3 requests, so this is almost always something else on the same token.