Skip to main content
API Reference

New Pages API endpoints reference

Two endpoints power your new pages integration: one to discover which pages exist and another to fetch the content for each page.

Robin AllensonBy Robin Allenson, CEO & Co-Founder
Get started with Similar AI

Overview

The New Pages endpoints tell your site which pages have been created and how to fetch the page details so you can render them. There are two endpoints:

  • 1.sitemap-page - Lists all page URLs as an XML sitemap.
  • 2.new-page - Returns the details for a specific page, including content, listings, and redirect information.

For the full onboarding walkthrough, see the new page onboarding checklist. For a broader overview of the feature, see the new pages user guide.

Sitemap-page endpoint

The sitemap-page endpoint lists all page URLs created through Similar AI as an XML sitemap. Use this to discover which pages exist and to submit them to Google Search Console.

Request

curl "https://dev-dot-isentropic-snow-282609.ew.r.appspot.com/s/sitemap-page.xml" \
  --header "X-SIMILARAI-DOMAIN: example.com"

Response

The response is a standard XML sitemap containing each page URL, its last modified date, change frequency, and priority.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/s/n/7-day-meditation</loc>
    <lastmod>2025-05-07</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.6</priority>
  </url>
</urlset>

Tip: Submit this sitemap to Google Search Console so Google can discover and index your new pages quickly.

New-page endpoint

The new-page endpoint returns the details for a specific page. Your backend calls this endpoint when a user visits a page, then renders the HTML from the returned content.

Request

curl -s --location --request POST \
  "https://dev-dot-isentropic-snow-282609.ew.r.appspot.com/api/new-page/" \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: api_key" \
  --data '{"path": "zen-meditation-retreat"}' \
  --http1.1 | jq

Method: POST

Headers: Content-Type: application/json, X-API-KEY: your_api_key

Body: {"path": "page-slug"}

Response: page with content

When the page has content, the API returns the listings and content fields you need to render the page.

{
  "listings": ["700LSSTG50B-LED927", "AH 3500GM"],
  "content": {
    "h1": "Zen Meditation Retreat",
    "title": "Zen Meditation Retreat - example.com",
    "blurb": "Discover peace and mindfulness..."
  }
}

Response: 301 permanent redirect

When a page has been permanently removed, the API returns a 301 status code and a redirect URL pointing to the homepage.

{
  "redirect_url": "https://example.com/",
  "status_code": "301"
}

Response: 302 temporary redirect

When a category page has no listings, the API returns a 302 temporary redirect. The page may come back once listings are available again.

{
  "redirect_url": "https://example.com/",
  "status_code": "302"
}

Redirect behavior

When a category page is removed, it is no longer returned by the sitemap-page endpoint. If the new-page endpoint is called for a removed page, the response includes a redirect_url field and a status_code.

ScenarioStatus codeMeaning
Page has no listings302Temporary redirect - the page may return when listings are added
Page permanently removed301Permanent redirect to the homepage

Your backend should check the response for a status_code field and issue the appropriate HTTP redirect to the user.

Caching and rendering

When a user views a page, your backend should call the new-page endpoint to fetch the page data, render the page in HTML, and return it to the user in real time. We recommend using a 24-hour cache for the new-page endpoint to reduce latency and avoid repeated calls for the same page.

Recommended cache TTL: 24 hours. This balances freshness with performance. Pages are updated periodically, and a daily cache refresh keeps your content current without unnecessary API calls.

Related guides

Frequently asked questions

What are the two core API endpoints used by the New Pages Agent?

The New Pages Agent relies on a sitemap-page XML endpoint for discovering which pages exist on your site, and a new-page JSON endpoint for retrieving full page details including content, redirects, and rendering data. Together these endpoints give the agent everything it needs to audit, create, and update pages autonomously.

What data should the new-page JSON endpoint return?

The new-page JSON endpoint should return structured data including the page's metadata, body content, redirect rules, and any rendered HTML the agent needs to evaluate. Providing complete and accurate payloads ensures the New Pages Agent can make well-informed decisions about content generation and page structure.

How does the sitemap-page XML endpoint support page discovery?

The sitemap-page XML endpoint exposes a machine-readable list of your site's existing pages so the New Pages Agent can identify coverage gaps and avoid duplicating content. Keeping this endpoint up to date means the agent always operates from an accurate picture of your current page inventory.

Do I need developer resources to implement these API endpoints?

Basic implementation requires a developer to expose the two endpoints from your existing platform or CMS, following the specifications in this reference guide. Once configured, Similar AI's agents handle all ongoing SEO work autonomously without further engineering involvement.

How do redirect rules in the new-page endpoint affect the New Pages Agent?

When the new-page JSON endpoint includes redirect data, the New Pages Agent uses it to avoid targeting URLs that are no longer canonical and to correctly attribute content to the right destination page. This prevents wasted crawl activity and ensures new pages are built around valid, indexable URLs.

Ready to start building with the New Pages API?

Get your API key and start integrating new pages into your e-commerce site today.

Request a demo