WonderRankWonderRankDOCS
Official Pull-Based Integration Protocol

WonderRank REST API & Headless Blog

Fetch and render generated, SEO/AEO/GEO-optimized articles programmatically into any static site generator (Next.js, Astro, Remix, Nuxt) or custom application. Pure JSON delivery authenticated with website-scoped Bearer tokens.

Pull-Based Simplicity

No public webhooks or server listener endpoints required. Your site fetches live content at build time or on demand.

Strict Single H1 Guarantee

Both content_html and content_markdown start with the intro and use H2s, never printing a duplicate H1.

Schema & Evidence Built-in

Complete with FAQ accordions, verified citation links, and pre-baked JSON-LD Article structured data.

AI

1. Let Your AI Assistant Write The Sync

You do not need to write integration boilerplate manually. Paste this prompt into Cursor, Claude Code, GitHub Copilot, or ChatGPT in your codebase. It builds the puller, dynamic route handlers, metadata generators, and JSON-LD schema injection matching your exact codebase conventions.

Prompt for AI Coding Assistants (Cursor / Claude Code / Copilot)
I use WonderRank to generate and publish SEO & AI-search optimized articles for my website. WonderRank provides a pull-based REST API that returns my published articles as clean JSON with HTML, Markdown, SEO metadata, JSON-LD schema, and source evidence. Build the code that pulls and renders them in this project. Match the language, framework, and conventions this project already uses.

The API:
- Endpoint: GET https://wonderrank.app/api/v1/articles
- Every request requires my Bearer token in the "Authorization: Bearer <token>" header. Read the token from an environment variable (e.g. WONDERRANK_API_TOKEN), never hardcode it. I will copy it from the WonderRank Integrations dashboard.
- Query parameters:
  - "status": "published" (default), "draft", "unpublished", or "all".
  - "per_page": 1 to 100 (default: 25).
  - "page": page number (default: 1).
  - "slug": optional filter for a specific article.
  - "id": optional filter for a specific immutable UUID.
- Response pagination envelope: articles sit inside "data: [...]", pagination information inside "meta" and navigation links under "links". Follow "links.next" until null to pull all pages.
- The API is strictly read-only: there are no endpoints that create, change, or delete content. Articles are planned and scheduled inside WonderRank, and pulled into your frontend on demand.
- Rate limits: 60 requests per minute. A 429 response means rate limit reached; respect the Retry-After header. A 401 response means the token is missing or wrong.

Each article object inside "data":
{
  "id": "7b8e5c3a-9f1d-4e2b-8a1c-3d4e5f6a7b8c",
  "title": "How to Build a Modern Headless Blog",
  "slug": "how-to-build-a-modern-headless-blog",
  "type": "post",
  "path": "/blog/how-to-build-a-modern-headless-blog",
  "status": "published",
  "published": true,
  "published_at": "2026-10-12T09:30:00Z",
  "unpublished_at": null,
  "published_url": "https://mybrand.com/blog/how-to-build-a-modern-headless-blog",
  "content_markdown": "Building a headless blog...",
  "content_html": "<p>Building a headless blog...</p><h2>Architecture</h2>...",
  "seo": {
    "title": "How to Build a Modern Headless Blog (2026 Guide)",
    "meta_description": "Learn the best strategies to build and scale a headless blog...",
    "target_keyword": "headless blog",
    "target_intent": "informational",
    "schema_json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"Article\",...}"
  },
  "og_image_url": "https://storage.wonderrank.com/blog-images/...",
  "og_image_alt": "Modern Headless Blog Architecture",
  "target_keyword": "headless blog",
  "categories": ["Engineering", "SEO"],
  "tags": ["headless blog", "jamstack"],
  "image": {
    "url": "https://storage.wonderrank.com/blog-images/...",
    "alt": "Modern Headless Blog Architecture"
  },
  "authors": [{ "name": "Jane Doe", "linkedin": "...", "twitter": "...", "avatar_url": "..." }],
  "publisher": "Acme SaaS",
  "key_takeaways": ["Decouple content from presentation", "Use ISR for sub-second page loads"],
  "faqs": [{ "q": "What is a headless blog?", "a": "A headless blog separates content from presentation..." }],
  "sources": [{ "claim": "Organic Traffic Growth Study", "url": "https://example.com/study", "year": "2026" }],
  "created_at": "2026-10-10T12:00:00Z",
  "updated_at": "2026-10-12T09:30:00Z"
}

Important Defensive Rules:
- "image.url" and "og_image_url" may be null if no featured image was set. Always check article.image?.url before rendering <img>.
- "authors" will contain [{ name: "..." }], but use article.authors?.[0]?.name || "Editorial Team" defensively.
- "published_at" may be null if status is draft. Check before calling new Date().

What the code should do:
1. Dynamic Route: Serve articles at /blog/[slug]. Render "title" as the page's <h1>, then render "content_html" below it (or parse "content_markdown"). Neither body field includes an <h1> (it starts with the intro and uses <h2> for subsections), ensuring the page ends up with exactly one <h1>.
2. SEO & Schema: Use "seo.title" for <title>, "seo.meta_description" for meta description, "image.url" for og:image, and inject "seo.schema_json_ld" into a <script type="application/ld+json"> tag in the HTML head.
3. SSG & Incremental Cache: If using Next.js or Astro, use generateStaticParams / getStaticPaths with a revalidation period (e.g. revalidate = 3600 or on-demand webhook revalidation).
4. FAQ & Sources: "content_html" already includes WonderRank's sanitized FAQ accordions and source citations.
5. Sitemap: Include all fetched article slugs in the sitemap.xml with "updated_at" as lastmod.
6. Unpublish Sync: When polling status=unpublished, drop or un-route matching articles locally so no taken-down content remains live.

Tell me where I paste my API token, the route file created, and how to verify locally.

2. Setting Up in WonderRank

Configuring REST API access takes under 30 seconds in the WonderRank dashboard:

  1. Open Dashboard → Integrations → REST API (Next.js / Headless).
  2. Target Website: Select your website from the dropdown selector. Each website is cryptographically isolated with its own Bearer token.
  3. Bearer Token: Click Generate New Token. Your token begins with wr_live_. Click Save API Configuration.
  4. Store the token securely in your application’s environment file (e.g. WONDERRANK_API_TOKEN=wr_live_...).
  5. Click Test Fetch in the dashboard to execute a live test request and inspect your published articles in real time.

3. Authentication & Headers

All requests to the WonderRank REST API must provide your access token as an HTTP Bearer token in the Authorization header:

// HTTP Request Headers
GET /api/v1/articles?status=published HTTP/1.1
Host: wonderrank.app
Authorization: Bearer wr_live_9a8b7c6d5e4f3a2b1c0d...
Accept: application/json
Security Best Practice: Keep your Bearer token in server-side environment variables or secret stores (Vercel, Cloudflare, Netlify). Never commit it to git or expose it in client-side browser bundles. Rotate your token anytime from the dashboard.

4. Endpoint & Query Parameters

GEThttps://wonderrank.app/api/v1/articles
ParameterTypeDefaultDescription
statusstring"published""published" (live pieces), "draft" (unreleased), "unpublished" (reverted/taken down), or "all".
per_pageinteger25Number of articles returned per page (min 1, max 100).
pageinteger1Pagination page index (1-based).
slugstringnullFilter by exact article slug for single-article fetching.
iduuidnullFilter by exact immutable article UUID.
Pure Read-Only Architecture

Like Blogr.ai, the WonderRank REST API is strictly pull-based and read-only. There are no endpoints to create, modify, or delete content programmatically.

Articles are planned, researched, and generated inside your WonderRank dashboard or automated scheduler. Whenever you click Publish (or when an article finishes generation), it instantly becomes available to your static site or Next.js app via GET /api/v1/articles.

5. JSON Response Inspector

Inspect the exact payload envelopes for single articles, paginated lists, and error status codes:

Response Payload — article_object.json
{
  "id": "7b8e5c3a-9f1d-4e2b-8a1c-3d4e5f6a7b8c",
  "title": "Programmatic SEO: The Definitive 2026 Playbook",
  "slug": "programmatic-seo-definitive-playbook",
  "type": "post",
  "path": "/blog/programmatic-seo-definitive-playbook",
  "status": "published",
  "published": true,
  "published_at": "2026-10-14T10:00:00Z",
  "unpublished_at": null,
  "published_url": "https://example.com/blog/programmatic-seo-definitive-playbook",
  "content_markdown": "Programmatic SEO allows high-growth teams to generate targeted landing pages at scale.\n\n## 1. Architecture Overview\n\nModern programmatic systems rely on structured dataset ingestion...",
  "content_html": "<p>Programmatic SEO allows high-growth teams to generate targeted landing pages at scale.</p><h2>1. Architecture Overview</h2><p>Modern programmatic systems rely on structured dataset ingestion...</p><details class=\"wr-faq-accordion\"><summary>What is Programmatic SEO?</summary><p>Programmatic SEO is the process of generating targeted, high-intent landing pages...</p></details>",
  "seo": {
    "title": "Programmatic SEO: The Definitive 2026 Playbook (Updated)",
    "meta_description": "Discover how modern teams automate programmatic landing pages, structure dataset schemas, and conquer AI search rankings.",
    "target_keyword": "programmatic seo playbook",
    "target_intent": "informational",
    "schema_json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"Article\",\"headline\":\"Programmatic SEO: The Definitive 2026 Playbook\",\"author\":{\"@type\":\"Person\",\"name\":\"Alex Mercer\"}}"
  },
  "og_image_url": "https://storage.wonderrank.com/blog-images/7b8e5c3a.png",
  "og_image_alt": "Programmatic SEO Playbook Cover",
  "target_keyword": "programmatic seo playbook",
  "categories": ["SEO", "Automation"],
  "tags": ["programmatic seo", "jamstack"],
  "image": {
    "url": "https://storage.wonderrank.com/blog-images/7b8e5c3a.png",
    "alt": "Programmatic SEO Playbook Cover"
  },
  "authors": [
    {
      "name": "Alex Mercer",
      "linkedin": "https://linkedin.com/in/alexmercer",
      "twitter": "https://twitter.com/alexmercer",
      "picUrl": "https://example.com/authors/alex.png"
    }
  ],
  "publisher": "Acme Software",
  "key_takeaways": [
    "Scale high-intent programmatic pages with automated topical workflows.",
    "Internal link architecture determines search engine crawl velocity."
  ],
  "faqs": [
    {
      "q": "What is Programmatic SEO?",
      "a": "Programmatic SEO is the process of generating targeted, high-intent landing pages using database-driven templates."
    }
  ],
  "sources": [
    {
      "id": "1",
      "claim": "Organic conversion rates by intent breakdown",
      "publisher": "Search Engine Land",
      "url": "https://searchengineland.com/study-2026",
      "year": "2026"
    }
  ],
  "created_at": "2026-10-12T14:30:00Z",
  "updated_at": "2026-10-14T10:00:00Z"
}

6. Field-by-Field Reference

Detailed breakdown of all properties returned in the article object:

PropertyTypeDescription
idstring (UUID)Immutable unique identifier in WonderRank. Match & upsert on this ID.
titlestringEditorial article title. Render this as the page's single <h1> tag.
slugstringURL-safe permalink slug (e.g., "how-to-automate-seo").
content_htmlstring (HTML)Sanitized HTML body with embedded FAQ accordions and verified citation links. Starts with introduction prose and uses H2s (never includes an H1).
content_markdownstring (MD)Raw Markdown source body without duplicate H1 headers for custom MDX pipelines.
seo.titlestringSearch-optimized meta title (often includes year or brand suffix).
seo.meta_descriptionstringHigh-CTR meta description optimized for SERP & AI answer summaries.
seo.schema_json_ldstring (JSON)Google-compliant Schema.org (Article + FAQPage). Inject into <head>.
image.urlstring (URL)High-resolution featured banner image CDN URL.
authorsarray of objectsAuthor E-E-A-T credentials (name, linkedin, twitter, picUrl).
faqsarray of objectsStructured Q&A pairs (q, a) for custom accordion components.
sourcesarray of objectsVerified research citations (claim, url, year).
tagsstring[]Category taxonomies and topic keywords.

7. Complete Integration Examples

Copy and adapt production-ready integration snippets in your stack of choice:

app/blog/[slug]/page.tsx
// ==============================================================================
// 1. BLOG FEED LISTING PAGE — app/blog/page.tsx
// ==============================================================================
import Link from 'next/link';

const API_BASE = 'https://wonderrank.app/api/v1/articles';
const API_TOKEN = process.env.WONDERRANK_API_TOKEN;

export const revalidate = 60; // Revalidate feed every 60s (ISR)

async function getArticles() {
  if (!API_TOKEN) throw new Error('Missing WONDERRANK_API_TOKEN environment variable');
  const res = await fetch(`${API_BASE}?status=published&per_page=50`, {
    headers: { Authorization: `Bearer ${API_TOKEN}` },
    next: { revalidate: 60 },
  });
  if (!res.ok) return [];
  const json = await res.json();
  return json.data || [];
}

export default async function BlogIndexPage() {
  const articles = await getArticles();

  return (
    <main className="max-w-6xl mx-auto px-6 py-16">
      <div className="mb-12">
        <h1 className="text-4xl sm:text-5xl font-black text-gray-900 tracking-tight mb-3">
          Latest Insights &amp; Articles
        </h1>
        <p className="text-lg text-gray-600">
          Curated guides, architectural breakdowns, and industry updates.
        </p>
      </div>

      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
        {articles.map((art: any) => (
          <article key={art.id} className="group flex flex-col bg-white border border-gray-200 rounded-2xl overflow-hidden shadow-xs hover:shadow-md transition-all">
            {art.image?.url && (
              <div className="aspect-video w-full overflow-hidden bg-gray-100">
                <img
                  src={art.image.url}
                  alt={art.image.alt || art.title}
                  className="w-full h-full object-cover group-hover:scale-105 transition-transform duration-300"
                />
              </div>
            )}
            <div className="p-6 flex-1 flex flex-col justify-between">
              <div>
                <span className="inline-block px-2.5 py-0.5 rounded-full text-xs font-bold bg-blue-50 text-blue-700 mb-3">
                  {art.categories?.[0] || 'Article'}
                </span>
                <h2 className="text-xl font-bold text-gray-900 group-hover:text-blue-600 transition-colors line-clamp-2 mb-2">
                  <Link href={`/blog/${art.slug}`}>{art.title}</Link>
                </h2>
                <p className="text-sm text-gray-600 line-clamp-3 mb-4">
                  {art.seo?.meta_description || ''}
                </p>
              </div>
              <div className="text-xs text-gray-400 font-medium">
                {art.published_at ? new Date(art.published_at).toLocaleDateString() : 'Draft'} • By {art.authors?.[0]?.name || 'Editorial Team'}
              </div>
            </div>
          </article>
        ))}
      </div>
    </main>
  );
}

// ==============================================================================
// 2. SINGLE ARTICLE DETAIL PAGE — app/blog/[slug]/page.tsx
// ==============================================================================
import { notFound } from 'next/navigation';
import type { Metadata } from 'next';

// Fetch single article by slug
async function getArticle(slug: string) {
  if (!API_TOKEN) throw new Error('Missing WONDERRANK_API_TOKEN environment variable');

  const res = await fetch(`${API_BASE}?slug=${slug}&status=published`, {
    headers: { Authorization: `Bearer ${API_TOKEN}` },
    next: { revalidate: 3600 }, // Cache and revalidate every hour (ISR)
  });

  if (!res.ok) return null;
  const json = await res.json();
  return json.data?.[0] || null;
}

// Pre-render all published article slugs at build time (SSG)
export async function generateStaticParams() {
  if (!API_TOKEN) return [];
  try {
    const res = await fetch(`${API_BASE}?status=published&per_page=100`, {
      headers: { Authorization: `Bearer ${API_TOKEN}` },
    });
    const json = await res.json();
    return (json.data || []).map((art: any) => ({ slug: art.slug }));
  } catch {
    return [];
  }
}

// Dynamic SEO Metadata Generation (Next.js 15+ / 16 compatible)
export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
  const { slug } = await params;
  const article = await getArticle(slug);
  if (!article) return {};

  const title = article.seo?.title || article.title;
  const description = article.seo?.meta_description || '';
  const imageUrl = article.image?.url || article.og_image_url;

  return {
    title,
    description,
    openGraph: {
      title,
      description,
      images: imageUrl ? [{ url: imageUrl, alt: article.image?.alt || title }] : [],
    },
  };
}

// Page Component with Single H1 & JSON-LD Schema
export default async function BlogPostPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const article = await getArticle(slug);
  if (!article) notFound();

  const authorName = article.authors?.[0]?.name || 'Editorial Team';
  const displayDate = article.published_at
    ? new Date(article.published_at).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
    : 'Draft';

  return (
    <article className="max-w-4xl mx-auto px-6 py-12">
      {/* Back to Blog Feed */}
      <div className="mb-6">
        <Link href="/blog" className="text-sm font-bold text-blue-600 hover:text-blue-800 transition-colors">
          &larr; Back to all articles
        </Link>
      </div>

      {/* Embedded JSON-LD Schema (Article + Breadcrumb + FAQPage Graph) */}
      {article.seo?.schema_json_ld && (
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: article.seo.schema_json_ld }}
        />
      )}

      {/* Featured Header */}
      <header className="mb-10">
        <h1 className="text-4xl sm:text-5xl font-black text-gray-900 tracking-tight mb-4">
          {article.title}
        </h1>
        <div className="flex items-center gap-4 text-sm text-gray-500">
          <time dateTime={article.published_at || ''}>{displayDate}</time>
          <span>• By {authorName}</span>
        </div>
      </header>

      {/* Hero Image (Defensive Null-Safety) */}
      {article.image?.url && (
        <div className="mb-10 rounded-2xl overflow-hidden border border-gray-200">
          <img src={article.image.url} alt={article.image.alt || article.title} className="w-full h-auto object-cover" />
        </div>
      )}

      {/* Clean Render of HTML Body (Starts with Intro + H2s) */}
      <div
        className="prose prose-lg prose-indigo max-w-none"
        dangerouslySetInnerHTML={{ __html: article.content_html }}
      />
    </article>
  );
}

8. Testing Your REST API

You can verify your connection in two ways:

Method 1: In-Dashboard Test Console

Go to Dashboard → Integrations → REST API. Click Test Fetch. WonderRank makes a real HTTP request to the endpoint using your saved token and renders the JSON response in the live inspector console.

Method 2: Terminal cURL

Run this command in your terminal:

curl "https://wonderrank.app/api/v1/articles?status=published" \ -H "Authorization: Bearer wr_live_your_token"

9. Troubleshooting Common Issues

401 Unauthorized errors

Verify that your Bearer token begins with "wr_live_" and that your request includes the "Authorization: Bearer <token>" header. If you generated a new token, make sure you clicked Save API Configuration in the dashboard.

422 Invalid parameter

The status query parameter only accepts "published", "draft", "unpublished", or "all". The per_page parameter must be an integer between 1 and 100.

429 Too Many Requests (Rate Limiting)

Requests are rate-limited to 60 per minute. Check the X-RateLimit-Remaining header on each response. If you hit 429, respect the Retry-After response header before repeating requests.

Articles not showing up immediately

By default, status=published only returns articles whose publication state is marked as published. Drafts or articles still in planning do not appear unless you supply status=all or status=draft.