Connect a Strapi site

Strapi is a headless CMS: it stores your content and serves it through an API, and a separate website displays it. Blog AI connects to Strapi's REST API with an API token, lets you choose the collection your posts live in and which of its fields gets each part of a post, and learns where each post appears from a post address pattern.

Our own blog runs on Strapi and is written with Blog AI, so this is the path we use every week.

Before you start

• Strapi 5 or Strapi 4, reachable at a public https:// address (not your own computer or a private network).
• Admin access to the Strapi admin panel, to create an API token.
• A collection for your posts, with any name (articles, blog-posts, insights…) and at least a title and a body field.
• Where posts appear on your website, for example https://www.example.com/blog/{slug}.

Create a token

1. In your Strapi admin panel, go to Settings → API Tokens and click Create new API Token. Name it "Blog AI".
2. Choose Full access (simplest: Blog AI can then read your exact field types too), or Custom with: find, findOne, create and update on your posts collection; find and create on your categories and tags; find on your authors; upload on Upload; and, optionally, getContentTypes and getComponents on Content-type-builder.
3. Copy the token: Strapi shows it once. You'll need a new one when it expires.

Connect

1. On Sites, click Add site and choose Strapi.

2. Website address: the public site your posts appear on, used for Google Search Console and post links.

3. Strapi address: your Strapi server, without /api or /admin at the end, for example https://cms.example.com. If you paste an admin panel address, Blog AI uses the server part and says so. Paste the API token and click Connect and choose your collection.

4. Collection: Blog AI lists the collections it finds, blog-like ones first, and picks the obvious one. Not listed? Type its API ID, the plural name in its API address (/api/blog-posts → blog-posts).

5. Field mapping: each row is a part of a Blog AI post; choose the Strapi field that gets it, or Don't fill. Blog AI suggests matches by name and type:

   • Title (required) and excerpt: text fields.
   • Slug: a UID or text field.
   • Body (required): Rich text (Markdown), Rich text (Blocks) or long text.
   • Meta title, meta description, canonical URL: text fields, including fields inside a component, shown as seo.metaTitle.
   • Featured image: a single media field.
   • Categories, tags: a relation to your categories or tags collection, or a text field.
   • Author: a relation (choose the author every post gets; an author entry with the name of the post's author is used instead, see Show who wrote your posts) or a text field.
   • Published date: a date field.

   A warning lists required fields Blog AI doesn't fill: drafts save, but Strapi won't publish until they have values. Another field… lets you type a field that isn't listed.

6. Post address pattern: {slug} stands for each post's address ending; the default is your website address followed by /blog/{slug}.

7. Test connection, then Add site and import posts. The test checks that the token can read the collection and may create and update entries, upload images and add categories and tags, without saving anything: Strapi has no dry run, so Blog AI sends empty requests that Strapi refuses before writing. Large blogs import in batches of 50; follow progress on the site card.

What Blog AI sends when it publishes

• Only the fields you mapped. Text is plain text, shortened to your field's maximum length; text shorter than a field's minimum (some SEO components want 50 characters) is left out with a warning.
• The body in your field's format. Markdown gets your call to action between two comment lines Blog AI uses to find it later. Blocks gets headings, paragraphs, bold, italic, underline, strikethrough, code, links, nested lists, quotes and code blocks; Blocks has no tables, so tables go as bulleted lists, and images inside the body go as links. Call-to-action blocks carry a small marker so Blog AI can replace them later.
• Featured image, uploaded to your media library.
• Categories and tags, matched by name and added when missing (if the token may); a single-relation field gets the first category. A subcategory goes as its own name (Guides › Payments as Payments). Author: the entry you chose.
• SEO component: on updates, its other fields (keywords, share image…) are kept.
• Scheduled posts wait in Blog AI and are sent within about five minutes of the time you picked.

Never done: Blog AI never deletes entries, never changes the slug of a live post, and never writes to your pages collection.

Also sent: the post's key takeaways and FAQ go in the body as sections (in a Markdown body they sit between hidden markers, so an update replaces them). With a field mapping you can also map a long text field to Structured data (JSON-LD).

Sites connected before collections and field mapping

They keep working exactly as before: an articles collection with title, slug, body (Markdown) and optional excerpt, seoTitle, seoDescription, meta_description, canonicalUrl, thumbnail, ogImage, category and tags. Under Fix connection this shows as Use Blog AI's standard article fields; untick it to choose your collection and fields.

Importing your website pages (optional)

If your pages live in a collection, open Fix connection in Settings, enter its API name under Pages collection (optional), click Test and save, then run Import posts and pages again. Pages are read-only. See Importing your existing posts and pages.

Common problems and fixes

"No "articles" collection at …/api"

Your posts are in a collection with another name (for example blog-posts), or the address is wrong. Use the server address without /admin or /api, then open Fix connection, untick Use Blog AI's standard article fields and choose your collection (or type its API ID).

"The address did not return Strapi REST data"

The address points at your website or the admin panel rather than the Strapi server, or a login page or firewall sits in front of it. Use the Strapi server address without /admin or /api: the one where …/api/<your collection> answers.

"Strapi rejected the API token (HTTP 401)"

The token is wrong or has expired. Create a new one and paste it under Fix connection.

"The API token can't read …" or "can read … but not create entries"

A Custom token lacks permissions. Add those in Create a token, or use Full access.

"Blog AI can't tell which collection … links to"

Blog AI couldn't read your schema and found no likely collection for that relation. Give the token getContentTypes on Content-type-builder and load the fields again, or set that row to Don't fill.

"The API token can't add entries to "…""

The category or tag doesn't exist yet and the token can't create it. Add it in Strapi, or give the token create on that collection.

Strapi rejected the request: "seo.metaTitle must be at most 60 characters"

A field has a rule Blog AI didn't know. Save the mapping again under Fix connection so Blog AI reads the current limits.

"The collection has no drafts in Strapi"

Draft & Publish is off, so saving a draft would publish it. Publish instead, or turn Draft & Publish on.

"This Strapi's articles body is not Markdown text"

(Standard fields only.) Your body is a Blocks field. Choose your collection and fields under Fix connection: with a mapped Blocks body, refreshes and Update live post work.

"The entry is not published on Strapi, so Blog AI left it alone"

Someone unpublished it in Strapi. Publish it there, then update again.

Headings show as ##, or the wrong image shows

Your website decides how it renders the body and which image field it shows. Render a Markdown body with a Markdown renderer and a Blocks body with Strapi's Blocks renderer.

Posts have no Google data

The post address pattern doesn't match where posts live. Compare a live post's address with the pattern and correct it under Fix connection.

"Strapi failed to … (HTTP 429)" or "(HTTP 502)"

Your host limited requests or was briefly down (free plans often sleep). Wait and click Retry publish; Blog AI updates the entry it already created.

See also Connection troubleshooting.