Build an internal
linking tool.

01 / Working example

Run the example

Choose cURL, JavaScript, or Python and use your API key. Keep the key on your server.

We’ll use our SEO copywriting article as the target and look for related posts that could link to it. The scan uses the keyword seo copywriting and region US. Replace the URL, keyword, and region to use your own page.

export ONPAGE_API_KEY="your-api-key"
# Generate once for this scan; keep the same key when retrying.
export ONPAGE_IDEMPOTENCY_KEY="$(openssl rand -hex 16)"

curl --include --fail-with-body --silent --show-error --max-time 30 \
  -X POST "https://api.on-page.ai/v1/scan" \
  -H "Authorization: Bearer $ONPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ONPAGE_IDEMPOTENCY_KEY" \
  --data '{
    "url": "https://blog.on-page.ai/seo-copywriting/",
    "keyword": "seo copywriting",
    "region": "US"
  }'

export ONPAGE_JOB_ID="job_id_from_the_scan_response"

curl --include --fail-with-body --silent --show-error --max-time 30 \
  "https://api.on-page.ai/v1/jobs/$ONPAGE_JOB_ID" \
  -H "Authorization: Bearer $ONPAGE_API_KEY"

curl --include --fail-with-body --silent --show-error --max-time 30 \
  "https://api.on-page.ai/v1/jobs/$ONPAGE_JOB_ID/result?response_format=customer_v1" \
  -H "Authorization: Bearer $ONPAGE_API_KEY"

02 / Response contract

Read the response

The scan submission returns job_id. Use it to poll the status endpoint until status is completed, then fetch the result. The status endpoint’s result field stays null.

Here’s the internal-linking section for our SEO copywriting article. Read report.internal_linking from the result endpoint; the fields are at the top level. The example JSON also gives you a test fixture to use while building your UI.

{
  "jobId": "job_d814dbab-2a93-4894-be77-dda73b15595a",
  "schema_version": "onpage-report-customer-v1",
  "internal_linking": {
    "add_internal_links_from": [
      "https://blog.on-page.ai/ai-and-copywriting/",
      "https://blog.on-page.ai/category/on-page/",
      "https://blog.on-page.ai/ai-writing-tools/"
    ],
    "to_your_url": "https://blog.on-page.ai/seo-copywriting/"
  }
}

add_internal_links_fromstring[]

Candidate source pages where your app could suggest a link to the target. Inspect their content to find a suitable placement.

to_your_urlstring

The destination for the suggested links. In this example, it’s our SEO copywriting article.

jobIdstring

The scan’s identifier. Store it with the suggestions for debugging.

On-Page.ai supplies the candidate URLs. Your application reads the page content, checks existing links, and chooses anchor text. This lets you bring the suggestions into your own editing workflow.

Internal linking is available in Standard and Deep scans. Lite scans omit this section.

Turn the response into application data

The JavaScript and Python examples print an object with jobId, targetUrl, and a candidates array. Each item has this shape. The examples add status so your app can track which suggestions still need review:

{
  "sourceUrl": "https://blog.on-page.ai/ai-and-copywriting/",
  "targetUrl": "https://blog.on-page.ai/seo-copywriting/",
  "status": "needs_review"
}

Store this data against the target page in your database. Use the source and target’s canonical URLs as a unique pair so processing the same report again won’t create duplicate suggestions.

03 / Application integration

Build the “suggested links” feature

Join the candidates to your CMS’s published articles. Your CMS adapter should return each article’s canonicalUrl and anoutgoingLinks array. Before calling the helper, resolve candidate URLs, article URLs, and outgoing links to their canonical URLs in your adapter, including relative links and redirects.

// articles: published articles from your CMS.
// The adapter resolves their URLs and outgoing links to canonical URLs.
function buildReviewQueue(candidates, articles) {
  const byUrl = new Map(
    articles.map((article) => [article.canonicalUrl, article]),
  );

  return candidates.filter(({ sourceUrl, targetUrl }) => {
    const article = byUrl.get(sourceUrl);
    if (!article) return false; // Archives aren't in the articles collection.
    return !article.outgoingLinks.includes(targetUrl);
  });
}

This keeps editable articles that don’t already link to the target. Let’s walk through the three pages returned for our example. Two are articles with relevant passages; the third is a category archive that already links to the target in its listing.

Add a link suggestion to your editor

Read each remaining article’s body from your CMS and find a relevant, unlinked phrase. The AI copywriting article already mentions optimizing content for search engines, a natural place to link to the SEO copywriting guide. Show the original text and proposed change together so the editor can review the placement:

Another key advantage of AI copywriting is its ability to <a href="https://blog.on-page.ai/seo-copywriting/">optimize content for search engines</a>.

The AI writing tools article offers another placement: “optimizing your writing for SEO”. Both suggestions connect an existing phrase to a guide that develops the topic, giving readers a useful next step.

If you use an LLM to select the phrase, give it the actual paragraph and target page content. Have it return a paragraph ID and exact anchor text. Your code should confirm that the phrase still exists outside a link, then add the link through your CMS’s editor API. Recheck the content revision before saving so a suggestion can’t overwrite a newer edit.

04 / Error handling

Handle job and result states