Strapi 5

RankPine supports Strapi 5 collection types through the official RankPine plugin or a scoped Content API token. Both methods use Strapi 5 documentId values, support Draft & Publish and i18n, upload featured media, and update an existing document instead of creating a retry duplicate.

Choose a connection method

The Marketplace plugin is the recommended path because it discovers the live schema and does not require a Strapi API token. The direct API-token method remains available when you cannot install a plugin.

Method 1: Strapi Marketplace plugin

Open the RankPine listing in Strapi Marketplace, or install the same public package directly:

npm install @rankpine/strapi-plugin-rankpine

Restart Strapi and rebuild or redeploy its admin panel through your normal deployment workflow. RankPine does not deploy your Strapi project.

Then open Settings → RankPine in Strapi:

1. Enter the public HTTPS URL of the Strapi server.
2. Select the target collection type.
3. Save settings.
4. Choose Connect RankPine.
5. Sign in to RankPine, choose the RankPine site, map every required article field, and approve the connection.

The pairing code expires after ten minutes and works once. RankPine generates an Ed25519 key pair server-side, sends only the public key to Strapi, and stores the private key encrypted in the tenant-scoped RankPine integration row. Strapi sends the code in a top-level HTTPS form POST, so it never appears in a URL.

Use Rotate connection to replace a key. Use Disconnect in either Strapi or RankPine to revoke it. If remote revocation cannot be confirmed, RankPine tells you to disconnect from Settings → RankPine in Strapi.

The plugin is also available on npm, and its source and issue tracker are on GitHub.

Method 2: scoped API token

1. Create the token

In Strapi, open Settings → Global settings → API Tokens and create a Custom token. Grant only:

• find, findOne, create, and update for the one target collection type;
• Upload find and upload when RankPine should set featured media.

Do not use a full-access token. Strapi keeps Content API tokens and Admin tokens strictly separate; RankPine never asks for an Admin token or admin login.

See Strapi's API token documentation.

2. Copy the schema

Copy the JSON from the collection's file in your Strapi project, for example:

src/api/article/content-types/article/schema.json

The Content API does not expose Content-Type Builder/admin metadata to a Content API token. RankPine therefore parses this explicit schema export instead of trying to cross Strapi's admin boundary. It contains field definitions, not content or credentials.

3. Discover and map

In RankPine, open Settings → Integrations → Strapi 5 and enter:

• public HTTPS Strapi URL, without /api;
• exact Strapi 5 version;
• content type UID, such as api::article.article;
• custom API token;
• enabled locale codes, with the default first, when the collection is localized;
• exported schema JSON.

Choose Discover fields. RankPine calls the collection with the token, rejects the Strapi 4 response shape, and displays the actual field types and required rules. Then map the fields and connect.

Field mapping

The article body is always explicit and required. RankPine sends each body field in its real Strapi format:

Blocks conversion does not synthesize inline media records: Markdown tables are preserved as Markdown code blocks, and inline image syntax becomes a safe link. Featured-media upload is the supported media attachment path.

Other mappings:

• title → String or Text;
• slug → UID, or a unique String;
• stable RankPine article ID → optional unique String/UID, recommended for strongest ambiguous-retry recovery;
• excerpt → String, Text, or Rich Text;
• SEO title/description and canonical URL → compatible top-level scalar fields;
• featured image → one image Media field;
• article date → Date, DateTime, or Timestamp using the stored article date;
• Boolean and Enumeration fields → explicit values you choose while connecting;
• Relations → explicit Strapi 5 documentId values.

RankPine never asks the publishing layer to invent a value for a custom field. A required unmapped scalar, relation, component, or dynamic zone blocks the connection or publish request.

Components and dynamic zones

Components and dynamic zones are discovered and shown, but are not written in this version. Optional structured fields remain untouched. A required component or dynamic zone is an error; RankPine does not silently drop it.

Other field types without an explicit RankPine publishing value—such as JSON, Integer, Big Integer, Decimal, Float, Email, Password, and Time—are also left untouched when optional and block the connection when required. System fields such as id, documentId, createdAt, updatedAt, publishedAt, createdBy, updatedBy, locale, and localizations are read-only; publication state and locale use Strapi's dedicated mechanisms instead.

To use that collection, either:

• make the structured field optional;
• expose the required article values as supported top-level fields; or
• choose a dedicated RankPine article collection.

Drafts, publishing, and locales

When Draft & Publish is enabled, RankPine sends Strapi's documented status=published or status=draft behavior explicitly. Draft mode leaves the RankPine article in Ready because Strapi has accepted it but it is not public. Publishing later updates the same document.

For localized collections, Match the RankPine article language sends the article variant's locale. A fixed configured locale is also available. The locale must exist in the configured Strapi locale list; RankPine never falls back to a different language silently.

See Strapi's REST status reference and REST locale reference.

Featured media

The API-token publisher:

1. checks Strapi Upload for the stable RankPine media identity;
2. downloads the RankPine image through the DNS-pinned SSRF-safe transport;
3. accepts JPEG, PNG, WebP, or GIF up to 10 MB and rejects SVG/active content;
4. uploads multipart form data to /api/upload;
5. attaches the returned media ID to the mapped field.

The Marketplace plugin applies the same public-HTTPS, DNS, redirect, decoded-file, size, format, and duplicate checks before it calls Strapi's Upload service.

See Strapi's Upload REST API.

Create, update, and retry behavior

• Normal updates use the documentId from the previous successful RankPine publish log.
• A create first looks for the stable RankPine article ID, when mapped; otherwise it checks the unique UID/slug.
• One matching document becomes an update. More than one match is an error.
• Media uses a stable per-article identity before upload.
• Inngest records the external documentId separately from the external call, so successful sibling integrations are not reposted after another destination fails.

This follows Strapi 5's document-based REST API, where create is POST /api/:pluralApiId and update is PUT /api/:pluralApiId/:documentId.

Troubleshooting

The plugin pairing link expired

Return to Settings → RankPine in Strapi and choose Connect RankPine again. Pairing codes work once and expire after ten minutes.

Signed request required

The plugin connection was revoked, its request timestamp is stale, or its nonce was already used. Rotate the connection from Settings → RankPine in Strapi.

Strapi rejected the API token (401)

Regenerate the token and reconnect. The raw token is shown by Strapi only according to your Strapi encryption-key configuration.

Strapi denied collection discovery or upload (403)

Check the custom token's exact collection permissions. Featured media also needs Upload find and upload.

Required field has no explicit value

Map the field, enter a Boolean/Enum/relation value, make it optional, or use a dedicated collection. RankPine will not generate a placeholder in the publishing layer.

Locale is not enabled

Refresh plugin discovery after enabling the locale in Strapi, or update the locale-code list in the API-token connection.