Skip to main content
API Reference

Server-Side Internal Linking API Integration

Integrate the Linking Agent API directly into your backend. One POST request returns anchor texts and destination URLs ready to render, with typical responses under 50 ms.

Robin AllensonBy Robin Allenson, CEO & Co-Founder
Request a Demo

How the Linking Agent API Works

The internal linking API returns a list of anchor texts and destination URLs for any page on your site. Each response may include an optional grouping so you can render a cluster of related links in a single section of the page, making navigation clearer for visitors and crawlers alike.

A typical response resolves within 50 ms. Most teams also cache the results locally since link data usually updates on a daily or weekly cadence. To further reduce latency, keep the HTTP connection open (persistent connections) for subsequent requests. Learn more about the Linking Agent on the Internal Linking platform page.

Request Format

Send a POST request to the Linking Agent endpoint with the following headers and body.

Required Headers

  • -X_API_KEY - your API key, provided during onboarding.
  • -User-Agent - a string identifying your application. For example: example corp/1.0 (+https://www.example.com)
  • -Content-Type: application/json

Request Body

POST /api/links HTTP/1.1
Content-Type: application/json
X_API_KEY: your-api-key
User-Agent: example corp/1.0 (+https://www.example.com)

{
  "url": "https://www.example.com/category/shoes"
}

The url field should contain the full URL of the page you want internal links for. The API will return links relevant to that specific page.

Response Format

The API returns one of two HTTP status codes depending on whether links are available for the given page.

HTTP 204 - No Links Available

If there are no internal links to show for this page, the API returns an HTTP 204 with an empty body. No further action is needed on your side.

HTTP 200 - Links Returned

When the Linking Agent has links for the page, you receive an HTTP 200 with a JSON body:

{
  "relatedSearches": [
    {
      "name": "running shoes for flat feet",
      "url": "https://www.example.com/guides/flat-feet-running-shoes"
    },
    {
      "name": "best trail running shoes",
      "url": "https://www.example.com/category/trail-running"
    },
    {
      "name": "shoe size guide",
      "url": "https://www.example.com/help/size-guide"
    }
  ]
}
  • -name - the anchor text to display for the link.
  • -url - the full destination URL the link should point to.

For details on rendering these links and handling the content payload, see the content payload guide.

Caching and Performance

While the API already responds within 50 ms in most cases, caching on your side removes the network round-trip entirely for repeat visitors. Here are the recommended strategies:

  • -Cache locally with a daily or weekly TTL. Link data changes infrequently, so a cache TTL of 24 hours covers most use cases. Refresh weekly if your catalog changes slowly.
  • -Keep connections alive. Use persistent HTTP connections (keep-alive) to avoid the overhead of a new TCP and TLS handshake on every request.
  • -Use a key-value store. Redis, Memcached, or even an in-memory map keyed by page URL works well. On cache miss, call the API and store the response.
// Pseudocode: fetch with cache
async function getInternalLinks(pageUrl) {
  const cacheKey = "links:" + pageUrl;
  let links = await cache.get(cacheKey);

  if (!links) {
    const response = await fetch(API_ENDPOINT, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X_API_KEY": process.env.SIMILAR_API_KEY,
        "User-Agent": "mysite/1.0 (+https://www.mysite.com)"
      },
      body: JSON.stringify({ url: pageUrl })
    });

    if (response.status === 204) {
      links = [];
    } else {
      const data = await response.json();
      links = data.relatedSearches;
    }

    // Cache for 24 hours
    await cache.set(cacheKey, links, { ttl: 86400 });
  }

  return links;
}

Alternative Integration Methods

Server-side integration gives you full control over caching and rendering, but it is not the only option. Depending on your stack, one of these approaches may be a better fit:

  • -WordPress plugin - one-click install for WordPress sites, handles API calls and rendering automatically.
  • -JavaScript / GTM integration - client-side snippet that loads links via JavaScript, useful when you cannot modify your backend.

Ready to Add Internal Links Server-Side?

The Linking Agent API integrates in minutes and responds in under 50 ms. Get your API key and start connecting your pages today.

Request a Demo