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 | jqMethod: 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.
| Scenario | Status code | Meaning |
|---|---|---|
| Page has no listings | 302 | Temporary redirect - the page may return when listings are added |
| Page permanently removed | 301 | Permanent 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
- New page onboarding checklist - Step-by-step setup for product feed, proxy, Google Search Console, and more.
- New pages user guide - How new pages work, what they look like, and how to manage them.
Ready to start building with the New Pages API?
Get your API key and start integrating new pages into your ecommerce site today.