How to Integrate Surfer SEO with Your Headless CMS

What is Surfer SEO?

Surfer SEO is an SEO platform used by content, editorial, and growth teams to plan, write, and score search-focused pages. Its core workflow centers on keyword research, Content Editor briefs, SERP analysis, topic suggestions, and content scoring based on competing pages. Teams often use Surfer SEO when they need repeatable guidance for articles, landing pages, product guides, and content refreshes.

Why integrate Surfer SEO with a headless CMS?

If your editors write in one place and check Surfer SEO in another, SEO work turns into copy, paste, score, revise, and repeat. A 40-article refresh project can mean hundreds of manual checks across target keywords, URLs, meta titles, headings, and body copy. That slows down publishing, and it makes it easy for the Surfer SEO brief, the published page, and the source content to drift apart.

Architecture overview

A typical Sanity and Surfer SEO integration starts when an editor publishes or updates an article in Sanity Studio. A webhook fires on the publish event, or a Function runs directly from the content mutation. The handler receives the document ID, then uses @sanity/client and a GROQ query to fetch only the fields Surfer SEO needs, such as title, slug, targetKeyword, metaDescription, locale, canonical URL, and Portable Text body converted to plain text. The server-side handler calls Surfer SEO's REST API with your Surfer API key, usually to create or update a Content Editor brief for the target keyword, country, language, and device. The response can be written back to Sanity as fields like surferContentEditorId, surferShareUrl, and lastSurferSyncAt, so editors can open the exact Surfer SEO brief from Sanity Studio. From there, the same structured article powers the website, preview experience, Surfer SEO workflow, mobile app, and any AI agent that reads approved content through Agent Context.

Common use cases

Step-by-step integration

1. 1

   Set up Surfer SEO API access

   Create or use an existing Surfer SEO workspace, confirm that API access is available on your plan, and generate an API key from your Surfer account settings or through your Surfer workspace admin. Keep the key server-side only.

2. 2

   Install the Sanity client and configure secrets

   Install @sanity/client in your Function, webhook listener, or middleware project. Add SANITY_PROJECT_ID, SANITY_DATASET, SANITY_READ_TOKEN, SURFER_API_KEY, and SURFER_API_BASE_URL as environment variables.

3. 3

   Model SEO fields in Sanity Studio

   Add fields such as targetKeyword, seoTitle, metaDescription, locale, canonicalUrl, surferContentEditorId, surferShareUrl, lastSurferSyncAt, and surferScore to your article schema. Keep the article body as Portable Text so you can query and convert it cleanly.

4. 4

   Create the sync trigger

   Use a GROQ-filtered webhook for article publish events, or use Functions to run server-side sync logic on mutations without a separate worker. Filter out documents without a targetKeyword to avoid unnecessary Surfer SEO calls.

5. 5

   Call Surfer SEO from the server

   Fetch the article with GROQ, build the Surfer SEO payload from structured fields, and call Surfer SEO's REST API with your API key. If your Surfer account uses different endpoint names or region-specific base URLs, follow the endpoint list in your Surfer API documentation.

6. 6

   Test the editor and frontend flow

   Publish a test article with a target keyword, confirm that Surfer SEO creates the brief, verify that the Surfer URL appears in Sanity Studio, and render the SEO fields on your frontend with the same content that was sent to Surfer SEO.

How Sanity + Surfer SEO works

CMS approaches to Surfer SEO

Keep building

Explore related integrations to complete your content stack.