Publish to any website with the REST API

curl --get "https://rankbox.xyz/api/public/v1/articles" \
  -H "Authorization: Bearer $RANKBOX_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "since=2026-10-01T09:30:00.123456+00:00"

const query = new URLSearchParams({ limit: "100" });
if (lastSince) query.set("since", lastSince); // URLSearchParams encodes the "+"
const res = await fetch(`https://rankbox.xyz/api/public/v1/articles?${query}`, {
  headers: { Authorization: `Bearer ${process.env.RANKBOX_API_KEY}` },
});
if (!res.ok) throw new Error(`Rankbox ${res.status}`);
const { articles, count, next_since } = await res.json();

import os
import requests

params = {"limit": 100}
if last_since:
    params["since"] = last_since  # requests encodes the "+"
res = requests.get(
    "https://rankbox.xyz/api/public/v1/articles",
    headers={"Authorization": f"Bearer {os.environ['RANKBOX_API_KEY']}"},
    params=params,
    timeout=20,
)
res.raise_for_status()
data = res.json()

import "server-only";

const API = "https://rankbox.xyz/api/public/v1";
const PAGE = 100;

export interface RankboxArticle {
  id: string;
  slug: string;
  title: string;
  description: string;
  body_markdown: string;
  body_html: string;
  tags: string[];
  seo_score: number;
  published_url: string | null;
  published_at: string;
  updated_at: string;
}

interface ArticlesPage {
  articles: RankboxArticle[];
  count: number;
  next_since: string | null;
}

async function rankbox<T>(path: string, init: RequestInit = {}): Promise<T> {
  const headers = new Headers(init.headers);
  headers.set("Authorization", `Bearer ${process.env.RANKBOX_API_KEY}`);
  const res = await fetch(`${API}${path}`, { ...init, headers });
  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(`Rankbox ${res.status}: ${body.error ?? res.statusText}`);
  }
  return res.json() as Promise<T>;
}

/** Every finished article. Next.js caches each page of results for an hour. */
export async function getAllArticles(): Promise<RankboxArticle[]> {
  const byId = new Map<string, RankboxArticle>();
  let since: string | null = null;
  for (let page = 0; page < 50; page++) {
    const query = new URLSearchParams({ limit: String(PAGE) });
    if (since) query.set("since", since);
    const data: ArticlesPage = await rankbox<ArticlesPage>(`/articles?${query}`, {
      next: { revalidate: 3600, tags: ["rankbox"] },
    });
    // The article at the cursor can come back at the top of the next page.
    for (const article of data.articles) byId.set(article.id, article);
    const more = data.count === PAGE && !!data.next_since && data.next_since !== since;
    since = data.next_since;
    if (!more) break;
  }
  return [...byId.values()];
}

/**
 * Find an article by slug. Slugs end with the first 8 characters of the
 * article id, so an article that was retitled (and got a new slug) can still
 * be found from its old URL and redirected.
 */
export async function findArticle(slug: string) {
  const articles = await getAllArticles();
  const exact = articles.find((a) => a.slug === slug);
  if (exact) return { article: exact, moved: false };
  const suffix = slug.slice(slug.lastIndexOf("-") + 1);
  const moved = /^[0-9a-f]{8}$/.test(suffix)
    ? articles.find((a) => a.id.startsWith(suffix))
    : undefined;
  return moved ? { article: moved, moved: true } : null;
}

/** Report the live URL of up to 100 articles Rankbox has no URL for yet. */
export async function reportLiveUrls(blogBase: string) {
  const { articles } = await rankbox<ArticlesPage>(`/articles?published=false&limit=${PAGE}`, {
    cache: "no-store",
  });
  let reported = 0;
  for (const article of articles) {
    try {
      await rankbox(`/articles/${encodeURIComponent(article.id)}`, {
        method: "PATCH",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ published_url: `${blogBase}/${article.slug}` }),
        cache: "no-store",
      });
      reported++;
    } catch (err) {
      // A 400 means the URL isn't on your Rankbox site's domain; every article would fail alike.
      return { reported, error: String(err) };
    }
  }
  return { reported };
}

import sanitizeHtml from "sanitize-html";

/** Article HTML, minus the opening <h1> your template already shows, sanitized. */
export function renderArticleHtml(html: string): string {
  const body = html.replace(/^\s*<h1[^>]*>[\s\S]*?<\/h1>\s*/i, "");
  return sanitizeHtml(body, {
    allowedTags: [...sanitizeHtml.defaults.allowedTags, "iframe"],
    allowedAttributes: {
      ...sanitizeHtml.defaults.allowedAttributes,
      iframe: ["src", "width", "height", "title", "allow", "allowfullscreen", "frameborder", "referrerpolicy"],
    },
    allowedIframeHostnames: ["www.youtube.com"],
  });
}

import type { Metadata } from "next";
import { notFound, permanentRedirect } from "next/navigation";
import { findArticle, getAllArticles } from "@/lib/rankbox";
import { renderArticleHtml } from "@/lib/rankbox-html";

export const revalidate = 3600; // re-check Rankbox at most once an hour

const SITE_URL = process.env.SITE_URL ?? "https://example.com";

type Props = { params: Promise<{ slug: string }> };

export async function generateStaticParams() {
  const articles = await getAllArticles();
  return articles.map((article) => ({ slug: article.slug }));
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const found = await findArticle((await params).slug);
  if (!found) return {};
  const { article } = found;
  const url = `${SITE_URL}/blog/${article.slug}`;
  return {
    title: article.title,
    description: article.description,
    keywords: article.tags,
    alternates: { canonical: url },
    openGraph: {
      type: "article",
      url,
      title: article.title,
      description: article.description,
      modifiedTime: article.updated_at,
      tags: article.tags,
    },
  };
}

export default async function ArticlePage({ params }: Props) {
  const found = await findArticle((await params).slug);
  if (!found) notFound();
  if (found.moved) permanentRedirect(`/blog/${found.article.slug}`);
  const { article } = found;
  return (
    <article>
      <h1>{article.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: renderArticleHtml(article.body_html) }} />
    </article>
  );
}

import { reportLiveUrls } from "@/lib/rankbox";

// Call this from a scheduler (for example hourly) with: Authorization: Bearer $CRON_SECRET
export async function GET(request: Request) {
  if (request.headers.get("authorization") !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response("Unauthorized", { status: 401 });
  }
  const base = `${process.env.SITE_URL ?? "https://example.com"}/blog`;
  return Response.json(await reportLiveUrls(base));
}

const API = "https://rankbox.xyz/api/public/v1";
const PAGE = 100;

export interface RankboxArticle {
  id: string;
  slug: string;
  title: string;
  description: string;
  body_html: string;
  body_markdown: string;
  tags: string[];
  seo_score: number;
  published_url: string | null;
  published_at: string;
  updated_at: string;
}

export async function getAllArticles(): Promise<RankboxArticle[]> {
  const byId = new Map<string, RankboxArticle>();
  let since: string | null = null;
  for (let page = 0; page < 50; page++) {
    const query = new URLSearchParams({ limit: String(PAGE) });
    if (since) query.set("since", since);
    const res = await fetch(`${API}/articles?${query}`, {
      headers: { Authorization: `Bearer ${import.meta.env.RANKBOX_API_KEY}` },
    });
    if (!res.ok) throw new Error(`Rankbox ${res.status}`); // fail the build rather than publish a partial list
    const data: { articles: RankboxArticle[]; count: number; next_since: string | null } =
      await res.json();
    for (const article of data.articles) byId.set(article.id, article);
    const more = data.count === PAGE && !!data.next_since && data.next_since !== since;
    since = data.next_since;
    if (!more) break;
  }
  return [...byId.values()];
}

---
import { getAllArticles } from "../../lib/rankbox";
import { renderArticleHtml } from "../../lib/rankbox-html"; // the same helper as the Next.js recipe

export async function getStaticPaths() {
  const articles = await getAllArticles();
  return articles.map((article) => ({ params: { slug: article.slug }, props: { article } }));
}

const { article } = Astro.props;
const html = renderArticleHtml(article.body_html);
const canonical = new URL(`/blog/${article.slug}`, Astro.site);
---
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{article.title}</title>
    <meta name="description" content={article.description} />
    <link rel="canonical" href={canonical} />
    <meta property="og:type" content="article" />
    <meta property="og:title" content={article.title} />
    <meta property="og:description" content={article.description} />
    <meta property="article:modified_time" content={article.updated_at} />
  </head>
  <body>
    <main>
      <article>
        <h1>{article.title}</h1>
        <Fragment set:html={html} />
      </article>
    </main>
  </body>
</html>

// Writes content/blog/rankbox/<slug>.md for every finished Rankbox article.
import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
import path from "node:path";

const API = "https://rankbox.xyz/api/public/v1";
const PAGE = 100;
const OUT = process.env.RANKBOX_OUT ?? "content/blog/rankbox";
const MANIFEST = path.join(OUT, ".rankbox-manifest.json"); // commit this file

async function getAllArticles() {
  const byId = new Map();
  let since = null;
  for (let page = 0; page < 50; page++) {
    const query = new URLSearchParams({ limit: String(PAGE) });
    if (since) query.set("since", since);
    const res = await fetch(`${API}/articles?${query}`, {
      headers: { Authorization: `Bearer ${process.env.RANKBOX_API_KEY}` },
    });
    if (!res.ok) throw new Error(`Rankbox ${res.status}: ${(await res.json()).error}`);
    const data = await res.json();
    for (const article of data.articles) byId.set(article.id, article);
    const more = data.count === PAGE && data.next_since && data.next_since !== since;
    since = data.next_since;
    if (!more) break;
  }
  return [...byId.values()];
}

const articles = await getAllArticles(); // a full walk, so deletions are seen
await mkdir(OUT, { recursive: true });
let manifest = {};
try {
  manifest = JSON.parse(await readFile(MANIFEST, "utf8"));
} catch (err) {
  if (err.code !== "ENOENT") throw err;
}

const q = (value) => JSON.stringify(value); // a JSON string or array is valid YAML
const next = {};
for (const a of articles) {
  const kept = manifest[a.id] ?? { slug: a.slug, date: a.updated_at }; // first slug and date win
  next[a.id] = kept;
  const body = a.body_markdown.replace(/^\s*#\s+[^\n]*\n?/, ""); // the template shows the title
  const file = [
    "---",
    `title: ${q(a.title)}`,
    `description: ${q(a.description)}`,
    `slug: ${q(kept.slug)}`,
    `date: ${q(kept.date)}`,
    `lastmod: ${q(a.updated_at)}`,
    `tags: ${q(a.tags)}`,
    `rankbox_id: ${q(a.id)}`,
    "---",
    "",
    body,
    "",
  ].join("\n");
  await writeFile(path.join(OUT, `${kept.slug}.md`), file);
}

// Remove files for articles that no longer exist in Rankbox.
const wanted = new Set(Object.values(next).map((k) => `${k.slug}.md`));
for (const name of await readdir(OUT)) {
  if (name.endsWith(".md") && !wanted.has(name)) await rm(path.join(OUT, name));
}
await writeFile(MANIFEST, JSON.stringify(next, null, 2));
console.log(`Rankbox: wrote ${articles.length} articles to ${OUT}`);

RANKBOX_API_KEY=rv_live_xxxxxxxxxxxx node scripts/pull-rankbox.mjs && hugo

curl -X PATCH "https://rankbox.xyz/api/public/v1/articles/$ARTICLE_ID" \
  -H "Authorization: Bearer $RANKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"published_url":"https://example.com/blog/how-to-price-a-saas-product-a1b2c3d4"}'

const res = await fetch(`https://rankbox.xyz/api/public/v1/articles/${encodeURIComponent(id)}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.RANKBOX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ published_url: `https://example.com/blog/${slug}` }),
});
if (!res.ok) throw new Error(`Rankbox ${res.status}: ${(await res.json()).error}`);
const { article } = await res.json(); // article.published_url is now set

import os
import requests

res = requests.patch(
    f"https://rankbox.xyz/api/public/v1/articles/{article_id}",
    headers={"Authorization": f"Bearer {os.environ['RANKBOX_API_KEY']}"},
    json={"published_url": f"https://example.com/blog/{slug}"},
    timeout=20,
)
res.raise_for_status()