Overview
The internal linking API returns a list of anchor texts and destination URLs for a page, with an optional grouping. Grouping lets you render a cluster of related links in one section of the screen.
If your Customer Success Manager has enabled it, the same response can also include generated content fields - title, h1, meta description, and a short blurb. This is useful when you use both our content and internal linking modules, because you only need one request per page instead of two.
A typical response resolves within 50 ms. Discuss your load requirements with your Customer Success Manager and cache responses locally. To reduce latency, keep the connection open for subsequent requests. For the standard linking-only API, see the server-side internal linking guide. For a broader overview of the feature, see the internal linking platform page.
Request format
Send a POST request to the endpoint provided by your Customer Success Manager. Include the following headers and body:
Headers
- -
X_API_KEY- Your API key - -
User-Agent- A string identifying your application
Body
POST /your-endpoint
Content-Type: application/json
X_API_KEY: your-api-key
User-Agent: your-app-name
{
"url": "https://www.example.com"
}Response schema
HTTP 204 - No data
If there are neither links nor content for the given page, the API returns HTTP 204 with no body.
HTTP 200 - Links and content
When data is available, the API returns HTTP 200 with a JSON object containing linking blocks and an optional content object:
{
"relatedSearches": [
{ "name": "<anchor text>", "url": "<destination URL>" },
{ "name": "<anchor text>", "url": "<destination URL>" }
],
"popularSearches": [
{ "name": "<anchor text>", "url": "<destination URL>" },
{ "name": "<anchor text>", "url": "<destination URL>" }
],
"content": {
"title": "title text",
"h1": "h1 text",
"meta_description": "meta description text",
"blurb": "Elevate your running game with our collection of premium running socks..."
}
}Linking blocks
Each top-level key in the response (other than content) is a linking block. A block contains an array of objects, each with a name (anchor text) and a url (destination URL).
The block name (for example relatedSearches or popularSearches) can be changed dynamically by our team or yours. You can use the key string directly as the section heading on the page, or hard-code your own heading if you prefer.
Content object
The content object contains generated page metadata and copy. The available fields are:
| Field | Type | Description |
|---|---|---|
| title | string | Suggested page title for the title tag |
| h1 | string | Suggested h1 heading text |
| meta_description | string | Suggested meta description for search results |
| blurb | string | Short descriptive copy for the page body |
If we do not have data for a content field, the key will still be present with an empty string as its value. Your integration should show either nothing or a default value depending on the field.
Performance and caching
- -Typical response time is under 50 ms. Discuss your load requirements with your Customer Success Manager.
- -Cache responses locally. Link and content data updates infrequently, so caching reduces round trips and keeps latency low.
- -Keep the connection open for subsequent requests to avoid repeated TCP/TLS handshakes.
Frequently asked questions
What does the Internal Linking API with Content Payload return in a single response?
The API returns both internal link recommendations and freshly generated page content - including the H1, title tag, meta description, and blurb - all in one request. This means your integration can update a page's copy and its internal linking structure simultaneously, reducing the number of API calls your pipeline requires.
How does combining linking and content generation in one payload save development time?
Rather than calling separate endpoints for link suggestions and content updates, your team can handle both concerns in a single response object. This simplifies the integration logic needed to keep Similar AI's Linking Agent and Content Agent outputs in sync across your product catalog.
Which Similar AI agents power the data returned in the content payload?
The Linking Agent supplies the internal link recommendations, identifying the most relevant anchor opportunities across your category and product pages. The Content Agent generates the accompanying H1, title, meta description, and blurb based on your keyword registry and topical strategy.
Is the Internal Linking API with Content Payload suitable for large product catalogs?
Yes, the API is designed for omni-channel retailers managing thousands of product and category pages. By batching link and content data into one payload, it keeps sync operations efficient even when processing updates across a broad catalog.
Can the content fields in the payload be used directly on product and category pages?
The returned H1, title, meta description, and blurb are generated to be production-ready, so they can be written directly to your CMS or storefront without additional processing. You can still apply your own post-processing logic if you need to enforce brand-specific formatting or tone guidelines.
Ready to integrate internal linking with content?
Talk to our team about enabling the combined linking and content payload for your integration.