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.
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.
Frequently asked questions
What does the Similar AI internal linking API actually return?
The API responds to POST requests with a structured payload containing anchor texts and destination URLs matched to the content on the page you're processing. Grouping support lets you organize links by category or topic cluster, making it straightforward to render contextually relevant links wherever they appear in your templates.
How fast is the internal linking API and can it handle real-time page rendering?
The endpoint is designed to respond in under 50ms, making it suitable for server-side rendering pipelines without adding noticeable latency to page load times. For high-traffic routes, the integration guide also includes caching guidance so repeated requests for the same page context are served instantly from your own layer.
Why integrate internal linking server-side rather than client-side?
Server-side integration ensures that anchor links are present in the initial HTML response seen by search engine crawlers, which is essential for passing link equity and signalling topical relationships to Google. Client-side injection risks links being ignored by crawlers that don't execute JavaScript fully, undermining the work the Linking Agent has done to map your site's topic clusters.
Does the API work across large catalogs with thousands of product and category pages?
Yes, the Similar AI internal linking API is built for omni-channel retailers carrying anywhere from 3,000 to 100,000 products, where manually maintaining link relationships is impractical. The Linking Agent continuously updates the underlying link graph as your catalog changes, so the API always returns current, relevant destinations without requiring manual intervention.
What caching strategy does Similar AI recommend for the internal linking API?
The integration guide recommends caching API responses at the page-template or URL level with a TTL aligned to how frequently your catalog and content change, typically hours rather than minutes. This approach balances freshness-ensuring newly created pages surfaced by the New Pages Agent or Content Agent enter your link graph promptly-with the performance benefit of avoiding redundant API calls on every render.
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.