API definitions

Defining lists of URLs, Sets, and Modules

Setting up a sitemap

What is a sitemap?

A sitemap is a file where you provide information about pages and other files on your website. Sitemaps are an important factor for SEO. Sitemaps allow for search engines to find and crawl pages on your website. For the purpose of the Internal Links API, we are only interested in the pages on your site rather than video, image or other file types. These pages will be used for putting together relationships between pages on your website and will be included in the output.

Google: Learn more about sitemaps here

Google: Build and submit a sitemap

Supported Sitemaps

  • Sitemap index with sub-sitemaps (preferred)
    • A sitemap URL pattern could also be specified to avoid crawling all sub-sitemaps in massive websites
  • XML sitemap
  • HTML sitemap
  • robots.txt file with sitemaps

Defining Sets

What is a Set?

Sets are subfolders or subdirectories on your website that are under the root domain of your site. These are how we build your Internal Links Modules. The same way that subfolders organize the content on your website, we use this organizational structure to inform our API how the links on your website are related.

Subdirectories are good for SEO as they can make your site easier to crawl (for bots) and navigate (for viewers). They allow for backlinks to pages contained in subdirectories and domain authority to remain closely connected to your root domain, which helps with ranking. Having to many levels of subdirectories can be negative for both user experience and for crawling your site.

We can work within multiple layers of subfolders; however, they need to be defined separately. Let's take the following URL structures as an example:

Set examples

Example 1:


In this example, we would need to define the top level subdirectories of both URLs, we would not be able to put these in one Module together under /products. The following Sets would be defined separately: /us, /uk and all pages that fall under these subdirectories would be considered in the API response.

In the event there are other types of pages that fall under /us such as /us/blog and /us/products, these can be specifically defined so that only the blog is included by defining the Set as /us/blog instead of defining at the top subdirectory level.

Example 2:


In this example, we would be able to look at all URLs contained under the /products subdirectory so any pages that fall in both /products/pricing and /products/demo we would be able to define together in one Set by naming the following Set: /products.

As with the first example, we can get more specific by defining more detailed subdirectory levels as needed.


How Sets are determined

Each Set will be used to determine your Modules separately, we are unable to combine multiple Sets into the source or target of one Module.

Subdomains as Sets

We can also point to subdomains as long as the subdomain structure doesn't conflict with any of the root domain structure. If two directories are named the same way in both the domain and subdomain there will be conflicts in providing accurate results in your Modules.

Subdomain example 1:


You can define your Set at the root level of your subdomain with / and we will look at and relate across all pages on your subdomain. This type of Set that relates across all pages should not be used if there are sitemaps for both the domain and the subdomain.

Subdomain example 2:

You can define subdirectories within your subdomain just as you would with a your root domain.


The Sets would be defined as /faq and /playbooks. This type of Set can be used if there are sitemaps for both a domain and a subdomain if there aren't any directories with the same names in the domain.

Defining Modules

All source and target Sets must first be defined in order to build the API configuration

What is a Module?

A Module contains all the remaining details to build your Internal Links configuration. This will help us know which Sets of pages will the Modules be on (the source), which Sets of pages will we be relating to (the target), and how many links we should provide in your API response for your to display on your page.

We recommend taking a look at some of the Design examples to get a better understanding of how this will look after implementation.



Contact our team to help put together an Internal Links strategy that will work for your site. We recommend having a strong Internal Links strategy in place to get the most benefit out of Internal Links and drive increases in organic traffic to your site.

Source Set

The source Set is the page type that your Internal Links Module will appear on. These pages are crawled and related to other pages in the target set.

Target Set

The target Set is the page type that your Internal Links Module will be linking to. These are related to the page from the source Set.

Number of Links

This is the numerical value of links to be returned in our API response to be displayed on the source pages.