Content API

Your site's server code reads its pages, SEO tags and sitemap from SuperDuperSEO, then renders them on your own domain. The SDK wraps all of this.

• Base URL: https://content.superduperseo.com/v1/
• Auth: Authorization: Bearer <site key> (sds_live_...). The key selects the site. Create it with the MCP tool create_site_key, or in the app on the site's Content API page.
• Server side only. Keep the key in your server environment (e.g. SUPERDUPERSEO_CONTENT_KEY), never in code or the browser. There is no CORS, so browsers cannot call the API.
• Never public, never indexed. Without a valid key every request answers 401, and every response carries X-Robots-Tag: noindex, nofollow, noarchive. Your domain is the only public copy.
• Caching: responses are Cache-Control: private, max-age=60 with an ETag; send If-None-Match to get 304. Cache on your side and refresh on our webhook.
• Limits: 20 requests a second per key (bursts of 200), then 429 with Retry-After.
• Errors: 401 wrong or revoked key; 404 no such file (a post that does not exist); 429 slow down.

Serving a request

For every path under your blog, in this order:

1. Redirects first. If the path is in redirects.json, answer 301 to to, or 410 when to is null.
2. The page. If posts/{slug}.json exists and its path is the request path, render it.
3. Otherwise a real 404, never a 200 page that says "not found".

Render on the server:

• <title> from seo.title;
• head_html in the <head>, removing your own description, canonical, Open Graph and Article JSON-LD so nothing is duplicated;
• the title as the only <h1>;
• then html.

Files

site.json (json)

The site: name, routes, feed, structured data.

Field	Type	Meaning
name	string	The site's name (as in og:site_name and structured data)
url	string	The site's home URL
language	string	Default content language
description	string | null	What the site is about
logo	string | null	Logo URL
routes	{ index, post, author, topic }	Where each kind of page lives, e.g. post: "/blog/{slug}"
feed	string	The RSS feed URL to serve
json_ld	object	Organization and WebSite structured data, for your home page

posts/index.json (json)

Published pages, newest first, 100 per file: { page, pages, total, next, posts: [summary] }. Follow next (posts/index-2.json...).

Field	Type	Meaning
id	string	Stable id of the page
collection	"blog" | "pages"	Blog post, or a service/SaaS/product page
slug	string	The public slug
path	string	The exact path to serve it at, e.g. /blog/my-post (no trailing slash)
url	string	The canonical URL on your domain
title	string	Title, rendered as the page's only
summary	string | null	One or two sentences: the meta description and the answer first
feature_image	{ url, alt, width, height, srcset, credit: { name, url, source } } | null	Feature image, with dimensions and srcset; show the credit when present
author	{ slug, name, url } | null	The byline's author
topics	Array<{ slug, name, url }>	Topic (cluster) the post belongs to
reading_time	number	Minutes
published_at	ISO 8601	First publish date (datePublished)
updated_at	ISO 8601	Last change to the content (dateModified, sitemap lastmod)

posts/{slug}.json (json)

One page with everything to render it.

Field	Type	Meaning
id	string	Stable id of the page
collection	"blog" | "pages"	Blog post, or a service/SaaS/product page
slug	string	The public slug
path	string	The exact path to serve it at, e.g. /blog/my-post (no trailing slash)
url	string	The canonical URL on your domain
title	string	Title, rendered as the page's only
summary	string | null	One or two sentences: the meta description and the answer first
feature_image	{ url, alt, width, height, srcset, credit: { name, url, source } } | null	Feature image, with dimensions and srcset; show the credit when present
author	{ slug, name, url } | null	The byline's author
topics	Array<{ slug, name, url }>	Topic (cluster) the post belongs to
reading_time	number	Minutes
published_at	ISO 8601	First publish date (datePublished)
updated_at	ISO 8601	Last change to the content (dateModified, sitemap lastmod)
html	string	The body: no , headings with ids, byline, calls to action and footer included. Render it as is, on the server
markdown	string	The same body as markdown (for /blog/{slug}.md or other renderers)
toc	Array<{ id, text, level }>	Table of contents from the h2/h3 headings
word_count	number	Words in the body
language	string	Content language, for
version	number	Increases with every content change
content_hash	string	Changes when the content changes
seo	{ title, description, canonical, robots, og, twitter }	Everything for the , as fields
json_ld	object	Structured data (@graph: Organization, WebSite, WebPage, BlogPosting, Person, BreadcrumbList, FAQPage...)
head_html	string	Ready-made tags: description, canonical, robots, Open Graph, Twitter and the JSON-LD. Not the