How to Integrate Clearscope with Your Headless CMS

What is Clearscope?

Clearscope is an SEO content platform for keyword research, content briefs, draft grading, and topic recommendations. Content, SEO, and editorial teams use it to compare drafts against top-ranking pages and see which terms, questions, readability targets, and word counts matter for a specific query. It's widely used by growth and enterprise SEO teams that need repeatable content scoring before an article goes live.

Why integrate Clearscope with a headless CMS?

If your team writes in one place and grades in Clearscope somewhere else, small errors pile up fast. An editor copies a 1,500-word draft into Clearscope, updates the H1 in the AI Content Operating System, forgets to paste the final version back, and ships copy with an old meta description. Multiply that by 40 articles per month, and your SEO workflow depends on memory instead of data flow.

Architecture overview

A typical Clearscope and Sanity integration starts when an editor updates an article in Sanity Studio. A webhook fires on a specific mutation, such as a publish event for documents where _type == 'article' and targetKeyword is defined. The webhook can call a Sanity Function, or the Function can be the event handler itself. Inside that handler, @sanity/client runs a GROQ query against the Content Lake to fetch the fields Clearscope needs, including title, SEO title, meta description, body text, slug, locale, and related category data. The handler converts Portable Text blocks into plain text, then calls the Clearscope REST API with the API key from an environment variable. Depending on your Clearscope plan and API access, that call creates or updates a content report for the target keyword and submitted draft text. The handler can then patch the Sanity document with the Clearscope report ID, report URL, grade, or last checked timestamp. Editors see those values in Sanity Studio, and the frontend renders the final article from the same structured document that was graded.

Common use cases

Step-by-step integration

1. 1

   Set up Clearscope API access

   Create or use a Clearscope account, request API access if it isn't already enabled on your plan, and generate an API key from your account settings. Clearscope API access is account-gated, so confirm the exact endpoint and payload names in your Clearscope documentation. For a TypeScript handler, install @sanity/client and use native fetch for the Clearscope REST API.

2. 2

   Model SEO fields in Sanity Studio

   Add fields that the integration can read and write, such as targetKeyword, seoTitle, metaDescription, locale, market, clearscopeReportId, clearscopeReportUrl, clearscopeGrade, and clearscopeLastCheckedAt. Keep editorial text in structured fields, not pasted HTML, so it can be converted into clean plain text for Clearscope.

3. 3

   Create a publish or review trigger

   Use a Sanity webhook or Function that runs only for the document types you want to grade, for example articles, guides, or landing pages. Add a filter so the sync runs when targetKeyword exists and the document moves to review or publish.

4. 4

   Fetch the exact content with GROQ

   Inside the handler, use @sanity/client to fetch only the fields Clearscope needs. GROQ can also join referenced data, such as category title or author name, if that context belongs in the content report.

5. 5

   Call Clearscope and write results back

   Send the keyword, title, body text, URL, language, and market to Clearscope's REST API. Then patch the Sanity document with the Clearscope report ID, report URL, grade, status, and timestamp so editors don't have to leave Sanity Studio to find the report.

6. 6

   Test with one content type before scaling

   Start with one article type and three test documents: a short draft, a long draft, and a document with missing SEO fields. Confirm API errors are visible to editors, retries don't create duplicate reports, and the frontend only displays content after the final approved version is published.

How Sanity + Clearscope works

CMS approaches to Clearscope

Keep building

Explore related integrations to complete your content stack.