> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seosorted.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Strapi

> Publish articles straight into a Strapi collection — created once, updated ever after.

The Strapi connector writes articles into a collection on your own Strapi instance using the
Content API. The entry lives in Strapi, exactly as if you had typed it into the admin panel, and
your site keeps reading it the way it always has.

## Step 1 — Create an API token

In Strapi: **Settings → API Tokens → Create new API Token**. Token type **Custom**, and grant:

| Permission                  | Why                                                                          |
| --------------------------- | ---------------------------------------------------------------------------- |
| `find` on your collection   | Verifies the connection when you connect                                     |
| `create` on your collection | First publish                                                                |
| `update` on your collection | Every republish                                                              |
| `upload`                    | Cover images. Optional — without it the entry still lands, without its cover |

Copy the token. Strapi shows it once.

## Step 2 — Connect

**Project Settings → Integrations → Strapi → Connect**.

<ParamField path="Strapi API URL" type="string" required>
  The instance itself, without `/api` — for example `https://cms.example.com`.
</ParamField>

<ParamField path="API token" type="string" required>
  The token from step 1.
</ParamField>

<ParamField path="Collection" type="string" required>
  The plural API id, as it appears in the URL `/api/<collection>`. Defaults to `ss-blogs`.
</ParamField>

<ParamField path="Site URL" type="string">
  Optional. Where the blog is published, so we can link you to the live post after publishing.
</ParamField>

<ParamField path="When an article is deleted here" type="string">
  What should happen in Strapi when you delete the article in SeoSorted. Defaults to **Do nothing**.
</ParamField>

We call the collection with your token before saving anything, so a wrong token or a mistyped
collection id fails at connect time rather than on your first publish.

## What we write

| SeoSorted                                | Strapi field                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| Title                                    | `title`                                                                  |
| Slug                                     | `slug`                                                                   |
| Body (markdown)                          | `content`                                                                |
| Meta description                         | `excerpt`                                                                |
| Featured image                           | `coverImage` (uploaded to Strapi's media library, on first publish only) |
| Meta title / description / focus keyword | `seo` component                                                          |
| Word count ÷ 200                         | `readTime`                                                               |
| —                                        | `publishDate` (time of publish)                                          |

Fields with no equivalent in SeoSorted — `author`, `tags`, `category`, `faq` — are left untouched,
so anything you set in Strapi survives a republish.

A republish also leaves `publishDate` and `coverImage` alone, and only overwrites `excerpt` when
the article actually has a meta description. The original publish date stays the original publish
date, and swapping the cover image inside Strapi is not undone the next time you publish.

## Publishing twice does not create a duplicate

The first publish creates the entry and we store its `documentId`. Every publish after that sends
a `PUT` to that same document, so the post is updated in place. This is the reason a republish
never leaves a second copy behind.

If you delete the entry inside Strapi and publish again from SeoSorted, the update fails — the
document is gone. Disconnect and reconnect to start clean.

## Deleting

By default, deleting an article in SeoSorted leaves the Strapi entry alone. That is deliberate:
clearing out drafts should not take a ranking post off your site.

The two other modes are opt-in per connection:

* **Unpublish it in Strapi** — the entry stays, moved back to draft. Reversible.
* **Delete it in Strapi** — the document is removed. **Not reversible**, and Strapi removes every
  locale of that document.

## Strapi 5 vs 4

The connector targets **Strapi 5**: string `documentId`s and the `?status=published` write flag.
Strapi 4 uses numeric ids and a `publishedAt` field instead, and is not supported.