How to Integrate Bolt.new with Ahrefs

Log in to your Ahrefs account and navigate to ahrefs.com/api or go to Account Settings → API. Ahrefs API v3 uses bearer token authentication — you'll find your token on the API settings page. Copy it carefully and store it somewhere safe. Before integrating, understand how Ahrefs credits work: each API endpoint costs a specific number of credits per call, and your plan has a monthly credit allocation. For example, fetching backlinks for a domain costs credits based on the number of rows returned. The Ahrefs API documentation at developer.ahrefs.com shows the credit cost per endpoint. To avoid burning credits during development, use Ahrefs' sandbox mode if available, or test with a low row limit (set `limit=5` or `limit=10` in API calls during development). Once you have your token, you're ready to configure Bolt. One more thing to check: Ahrefs API v3 base URL is `https://api.ahrefs.com/v3/`. The authorization header format is `Authorization: Bearer YOUR_TOKEN_HERE`. The API returns JSON with a predictable structure — most endpoints return a `data` array with metric objects. Review the API reference for the specific endpoints you'll use (site-explorer/overview, backlinks, organic-keywords) before building your dashboard so you understand the response shape.

1// lib/ahrefs.ts
2const AHREFS_BASE_URL = 'https://api.ahrefs.com/v3';
3
4export async function callAhrefsAPI(
5  endpoint: string,
6  params: Record<string, string | number> = {}
7): Promise<any> {
8  const apiKey = process.env.AHREFS_API_KEY;
9  if (!apiKey) {
10    throw new Error('AHREFS_API_KEY environment variable is not set');
11  }
12
13  const url = new URL(`${AHREFS_BASE_URL}/${endpoint}`);
14  Object.entries(params).forEach(([key, value]) => {
15    url.searchParams.set(key, String(value));
16  });
17
18  const response = await fetch(url.toString(), {
19    headers: {
20      Authorization: `Bearer ${apiKey}`,
21      Accept: 'application/json',
22    },
23  });
24
25  if (!response.ok) {
26    const error = await response.text();
27    throw new Error(`Ahrefs API error ${response.status}: ${error}`);
28  }
29
30  return response.json();
31}

Now create the Next.js API route that the frontend will call. This route acts as a secure proxy between your Bolt app and the Ahrefs API — it runs server-side, reads the API key from environment variables, calls Ahrefs, and returns the formatted data to the browser. The key security point is that this route lives in `app/api/` and is never bundled into client-side JavaScript. The browser calls your own Next.js route at `/api/ahrefs/overview?domain=example.com`, your route calls Ahrefs with the bearer token, and returns the response. This pattern prevents your Ahrefs credentials from ever reaching the browser — critical because Ahrefs API credits are tied to your account and leaked credentials could be abused by anyone. The route validates the incoming request, catches API errors gracefully, and formats the Ahrefs response into a clean shape for the frontend. Input validation prevents malicious domains or SQL injection patterns from reaching the Ahrefs API. Always sanitize the domain parameter before using it in API calls.

1// app/api/ahrefs/overview/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { callAhrefsAPI } from '@/lib/ahrefs';
4
5export async function GET(request: NextRequest) {
6  const domain = request.nextUrl.searchParams.get('domain');
7
8  if (!domain) {
9    return NextResponse.json(
10      { error: 'domain parameter is required' },
11      { status: 400 }
12    );
13  }
14
15  // Basic sanitization
16  const cleanDomain = domain.replace(/[^a-zA-Z0-9.-]/g, '').toLowerCase();
17
18  try {
19    const data = await callAhrefsAPI('site-explorer/overview', {
20      target: cleanDomain,
21      mode: 'domain',
22      limit: 10,
23    });
24
25    return NextResponse.json({
26      domain: cleanDomain,
27      domainRating: data?.metrics?.domain_rating ?? 0,
28      backlinks: data?.metrics?.backlinks ?? 0,
29      referringDomains: data?.metrics?.referring_domains ?? 0,
30      organicTraffic: data?.metrics?.organic_traffic ?? 0,
31    });
32  } catch (error) {
33    const message = error instanceof Error ? error.message : 'Unknown error';
34    return NextResponse.json({ error: message }, { status: 500 });
35  }
36}

With the overview route working, extend the integration to fetch actual backlink data. The Ahrefs `site-explorer/backlinks` endpoint returns individual backlinks with their source URL, anchor text, domain rating, link type (follow/nofollow), and first-seen date. This data enables building a proper backlink explorer where users can filter by domain rating, sort by link quality, and identify the most valuable links pointing to any domain. The dashboard UI uses React state to manage the search input, loading states, and the fetched data. Error states must be handled gracefully — Ahrefs returns meaningful error messages when credits are exhausted or when a domain has no data in the index. A key UX consideration: fetching 100 backlinks can take 2-3 seconds over the Ahrefs API. Show a loading spinner and disable the search button while fetching to prevent duplicate requests that would waste credits.

1// app/api/ahrefs/backlinks/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { callAhrefsAPI } from '@/lib/ahrefs';
4
5export async function GET(request: NextRequest) {
6  const domain = request.nextUrl.searchParams.get('domain');
7  if (!domain) {
8    return NextResponse.json({ error: 'domain is required' }, { status: 400 });
9  }
10
11  const cleanDomain = domain.replace(/[^a-zA-Z0-9.-]/g, '').toLowerCase();
12
13  try {
14    const data = await callAhrefsAPI('site-explorer/backlinks', {
15      target: cleanDomain,
16      mode: 'domain',
17      limit: 20,
18      order_by: 'domain_rating_source:desc',
19    });
20
21    const backlinks = (data?.backlinks ?? []).map((bl: any) => ({
22      urlFrom: bl.url_from,
23      domainRating: bl.domain_rating_source,
24      anchor: bl.anchor,
25      isDofollow: bl.is_dofollow,
26      firstSeen: bl.first_seen,
27    }));
28
29    return NextResponse.json({ domain: cleanDomain, backlinks });
30  } catch (error) {
31    const message = error instanceof Error ? error.message : 'Unknown error';
32    return NextResponse.json({ error: message }, { status: 500 });
33  }
34}

The Ahrefs API works fine during development in Bolt's WebContainer — outbound HTTPS calls to api.ahrefs.com succeed because WebContainers support all outbound HTTP traffic. However, the `.env` file you created is only for local development. When you deploy to Netlify or Bolt Cloud, the environment variables must be configured in the hosting platform's dashboard — they are not read from the `.env` file in production. For Netlify: connect your Bolt project via Settings → Applications → Netlify, click Publish, then go to the Netlify dashboard → Site Configuration → Environment Variables and add `AHREFS_API_KEY` with your actual bearer token. For Bolt Cloud: click Publish → use the Secrets panel to add the variable before publishing. After adding environment variables, redeploy the site (Netlify triggers a new deploy automatically when env vars change; Bolt Cloud requires re-clicking Publish). Verify the deployment by visiting your deployed URL and testing the domain search form. If the API calls fail on the deployed site but worked in the preview, it's almost always a missing or incorrectly named environment variable.

1// app/admin/deploy-check/page.tsx
2'use client';
3import { useState } from 'react';
4
5export default function DeployCheck() {
6  const [status, setStatus] = useState<'idle' | 'checking' | 'ok' | 'error'>('idle');
7  const [message, setMessage] = useState('');
8
9  const checkConnection = async () => {
10    setStatus('checking');
11    try {
12      const res = await fetch('/api/ahrefs/overview?domain=ahrefs.com');
13      const data = await res.json();
14      if (res.ok && data.domainRating !== undefined) {
15        setStatus('ok');
16        setMessage(`Connected. ahrefs.com DR: ${data.domainRating}`);
17      } else {
18        setStatus('error');
19        setMessage(data.error ?? 'Unknown error');
20      }
21    } catch (e) {
22      setStatus('error');
23      setMessage('Network error — API route unreachable');
24    }
25  };
26
27  return (
28    <div style={{ padding: 32 }}>
29      <h1>Ahrefs API Connection Check</h1>
30      <button onClick={checkConnection} disabled={status === 'checking'}>
31        {status === 'checking' ? 'Checking...' : 'Test Connection'}
32      </button>
33      {status === 'ok' && <p style={{ color: 'green' }}>{message}</p>}
34      {status === 'error' && <p style={{ color: 'red' }}>Error: {message}</p>}
35    </div>
36  );
37}