How to Integrate Ahrefs with Your Headless CMS

What is Ahrefs?

Ahrefs is an SEO platform used by search teams, content marketers, agencies, and growth teams to research keywords, analyze backlinks, audit sites, and track organic visibility. Its core strength is search data, including Site Explorer, Keywords Explorer, Rank Tracker, Content Explorer, and Site Audit. Teams use Ahrefs to decide what to publish, which pages to refresh, and where search performance is gaining or losing ground.

Why integrate Ahrefs with a headless CMS?

SEO work gets messy when content lives in one place and search data lives somewhere else. An editor publishes a landing page, an SEO lead checks Ahrefs a week later, and a developer exports a CSV before the next sprint. By the time the team sees that a URL has zero referring domains or is ranking for the wrong query, the publishing window has already passed.

Architecture overview

A typical Sanity and Ahrefs integration starts when an editor publishes or updates a document in Sanity Studio. A GROQ-powered webhook filters for the document types you care about, such as articles, landing pages, or docs pages, and sends the document ID to a Sanity Function or webhook listener. The Function uses @sanity/client to fetch the published record from the Content Lake with a GROQ query that returns only the fields Ahrefs needs, usually the canonical URL, slug, title, target keyword, locale, and related topic references. The Function then calls the Ahrefs API, commonly endpoints under Site Explorer for URL metrics, organic keywords, referring domains, backlinks, or broken backlinks. Ahrefs returns search metrics for that URL or domain. The Function patches those results back into the same Sanity document, or into a separate seoMetric document if you want historical snapshots. Editors see the data in Sanity Studio, frontend code can query it for reporting pages, and downstream systems can use the same structured content for web, mobile, analytics dashboards, and AI agents.

Common use cases

Step-by-step integration

1. 1

   Set up Ahrefs API access

   Create or use an Ahrefs account with API access, generate an API token from the Ahrefs API settings, and note which endpoints your plan supports. For a Node or TypeScript build, you can call the REST API with fetch. Ahrefs does not provide a first-party SDK for every endpoint, so direct HTTP requests are the safest option.

2. 2

   Model SEO fields in Sanity Studio

   Add fields such as canonicalUrl, targetKeyword, seoTitle, metaDescription, noindex, and ahrefsMetrics to your article, product, or landing page schemas. Keep Ahrefs results in a nested object for current metrics, or create a separate seoSnapshot document if you want daily or weekly history.

3. 3

   Create a publish trigger

   Add a Sanity webhook that fires on publish events for the document types you want to track. Use a GROQ filter such as _type in ['post', 'landingPage'] && defined(slug.current) so drafts, media-only changes, and unrelated documents do not call Ahrefs.

4. 4

   Fetch the exact fields with GROQ

   In your Sanity Function or webhook handler, fetch the published document from the Content Lake. Use GROQ projections to return the canonical URL, target keyword, title, locale, and referenced category data without pulling the full document tree.

5. 5

   Call the Ahrefs API and write metrics back

   Call Ahrefs Site Explorer endpoints with the page URL and mode=exact, then patch the returned backlink, referring domain, and organic keyword metrics back to Sanity. Add rate-limit handling because Ahrefs API credits are plan-dependent.

6. 6

   Test the editor and frontend experience

   Publish a test page, confirm the webhook fires, verify the Ahrefs response, and check that Sanity Studio shows the updated metrics. On the frontend, query the same fields to build SEO dashboards, content inventory reports, or refresh queues.

How Sanity + Ahrefs works

CMS approaches to Ahrefs

Keep building

Explore related integrations to complete your content stack.