Skip to main content
Every other connector pushes articles into a CMS. The Headless API works the other way round: your site pulls published articles from SEO Sorted with a read-only blog key, and renders them with your own components, routes and styles. Use it when your blog is code, not a CMS — a Next.js app, an Astro site, a custom React frontend, a mobile app, or a Framer/Webflow page that fetches JSON.

5-minute setup

One environment variable and one fetch helper.

SEO built in

Meta title, description, JSON-LD, canonical URL and a sitemap endpoint.

Your design

Ready-rendered HTML and markdown — style it however you like.

How it works

  1. You connect the Headless API and get a blog key (ss_blog_…).
  2. You publish an article to Headless API (Next.js) — manually, on a schedule, or with auto-publish.
  3. We save a snapshot of the article. It is in the API immediately.
  4. Your site fetches GET /api/v1/content/articles and GET /api/v1/content/articles/{slug} and renders them.
Editing an article in SEO Sorted does not change the live post until you Re-publish it — the same rule as every other destination. Unpublishing or deleting the article removes it from the API.

Step 1 — Get your blog key

Project Settings → Integrations → Headless API (Next.js) → Connect.
Connect Headless API dialog with a short explanation, a Site URL (optional) field and a Generate blog key button

The Headless API connect form

string
Where your blog is served. Defaults to your project’s website. We use it, plus the content path from Project Settings (/blog by default), to build each article’s live url.
Click Generate blog key. The panel that opens shows the key, the API base URL, and three tabs — Next.js, cURL and AI prompt — with copy-paste snippets. Open it again any time from the card’s ⋮ menu → View key & setup.
The key is read-only: it can only list articles you have already published — content that is public on your site anyway. Still, keep it server-side and out of client bundles. Regenerate key invalidates the old one immediately.

Step 2 — Add the key to your site

.env.local
Add the same variable in your host’s settings (Vercel → Project → Settings → Environment Variables, Netlify, etc.).

Step 3 — Fetch articles

lib/seosorted.ts
app/blog/page.tsx
app/blog/[slug]/page.tsx
app/blog/sitemap.xml/route.ts
The article html uses plain semantic tags (h2, p, ul, table, blockquote, img, YouTube iframe). Wrap it in Tailwind Typography’s prose class and it looks right with no extra CSS.

Let an AI assistant build it

The setup panel’s AI prompt tab contains a complete brief — endpoints, types, and the pages to build — with your API URL filled in. Paste it into Cursor, Claude Code, v0 or Lovable and it will add a full blog (index, article, category and tag pages, sitemap) to your project.

Step 4 — Publish

Open any finished article → Publish → Publish now next to Headless API (Next.js). Or set it as the destination for scheduled and auto-published articles. The dialog confirms “Live in the Headless API — your site will pick it up on its next fetch”, with a View article button pointing at the url built from your Site URL. The article is in the API as soon as the publish job finishes; with revalidate: 300 your site shows it within five minutes.

Re-publishing, unpublishing and deleting

  • Re-publish overwrites the same snapshot — same id, new updatedAt.
  • Unpublish and deleting the article remove it from the API immediately; its slug returns 404.
  • Disconnecting the Headless API deletes every snapshot it served. Your site’s blog goes empty until you connect again and publish the articles again.
Want it instantly? Add an on-demand revalidation route to your site and point a Webhook connector at it — but note a workspace holds one connector per kind, so the webhook is an extra, not a replacement.

API reference

Base URL: https://seosorted.ai/api/v1/content. Every response is wrapped as { "data": … }; errors are { "error": { "code", "message" } }.

Authentication

Send the key as a bearer token:
X-Api-Key: ss_blog_… and ?key=ss_blog_… also work, for tools that can’t set an Authorization header.

Endpoints

Interactive reference with every schema: seosorted.ai/api/v1/reference.

Fields

object
ArticleIndex +

Limits and caching

  • 600 requests per minute per key. Over that you get 429 with retryAfterSeconds.
  • Responses carry Cache-Control: private, max-age=60, stale-while-revalidate=300. Cache on your side — Next.js revalidate, ISR or a CDN — rather than calling the API on every page view.
  • CORS is open, so the API works from the browser too. Prefer server-side fetching so the key stays out of your bundle.

Moving from SEObot

The response shapes match SEObot’s IArticle / IArticleIndex, so your templates keep working. Swap the client calls:

Tracking AI crawlers

Track AI crawlers on the frontend that renders your pages, not on the API. Pick your framework and host in Which option to pick.

Troubleshooting

The key was regenerated, or copied with a missing character. Copy it again from View key & setup and redeploy so your host picks up the new environment variable.
Only articles published to Headless API appear — not drafts, and not articles published to another connector. Publish one and check again.
The API serves what you last published. Click Re-publish on the article. If it is already re-published, your site’s cache (revalidate) may still be holding the old copy.