Publish to any website

When to use it

For the websites Kleos doesn't connect to

Set-up

Four steps in Kleos

You need a Kleos workspace on a plan with the API, and to be its owner or an admin.

1. 1

   Make an API key with write access

   In Kleos, go to Settings → API. Under API keys, make a key with “Read and write” and copy it: it is shown once. Recording the live link is a write; listing articles only needs a read key. Only workspace owners and admins can make keys.

2. 2

   Add a webhook endpoint

   Go to Settings → API → Webhooks. Enter your endpoint's address (https only, on the standard port), an optional description, and tick the events to send: article.approved, and article.published if other tools should hear when it is live. Press Add endpoint.

3. 3

   Copy the signing secret

   The secret (whsec_…) is shown once, right after the endpoint is added. Store it where your receiver can read it, as an environment variable, and never in the page's code. Rotate secret makes a new one and keeps the old one signing for a day.

4. 4

   Send a test event

   Press Send test event on the endpoint. Kleos sends one webhook.test event now and shows the response code and how long your endpoint took. The recent deliveries list under the endpoint shows every payload and attempt for the last month.

The article

The fields in data

Everything a page needs, so your receiver has nothing else to fetch: the text twice (Markdown and HTML), the search title and description, an excerpt, the hero image, the FAQ, the language and your site's address.

id

The article's id in Kleos. Keep it with the page: PATCH /v1/articles/{id} uses it, and a re-approval arrives with the same id.

product_id

The business it belongs to (business_id in the webhook envelope).

title

The headline.

slug

A URL-safe name for the page, or null. Use it as the page's address when your CMS allows.

status

approved in article.approved; published in article.published. The API lists brief, draft, pending_approval, approved, published or failed.

primary_keyword

The search phrase the article aims at, or null.

meta_title

A search title for the page's <title> and og:title, or null.

meta_description

A search description, or null.

body_md

The article's text in Markdown, as GET /v1/articles/{id} returns it: headings, lists and links.

body_html

The same text as HTML for a page whose title your CMS sets: the body without its title heading, with the FAQ as a closing section. The same renderer as the app's HTML download.

excerpt

A short summary: the search description, else the opening paragraph.

hero_image

{url, alt} for the article's hero image, or null when it has none. The link is signed and good for 7 days: download the image into your site rather than hot-linking it.

faq

Question-and-answer pairs Kleos wrote for the article, as {question, answer} objects. Often empty. Already rendered into body_html.

canonical_url

The address Kleos holds as the article's home: null until the live link is recorded, then the same as external_url.

language

BCP 47, for example en-US or es, for the page's lang attribute.

site_url

The business's website as set in Kleos, for building the page's address.

external_url

The live address once recorded, or null.

published_at

When it was recorded as published, or null.

created_at

updated_at: when it was made and last changed.

GET /v1/articles/{id} returns the same article without body_html, excerpt, hero_image, canonical_url, language and site_url (those are built for the event); GET /v1/articles?status=approved lists what is ready without the text. Both take a read key.

Closing the loop

Tell Kleos where the article lives

Kleos needs the page's address to count the article as published and to keep the live link with it (on the article's page, in the API's external_url and in the article.published event). PATCH /v1/articles/{id} with {"external_url": "https://…"} and a key with write access does it: approved articles only, https only. Kleos opens the link first: a page that doesn't exist (404 or 410) is refused with a 422, so make the call after the page is live, not before a deploy; a site that blocks automated visitors is accepted. The response is the article, now published. The same for a social post that went out through another tool: PATCH /v1/posts/{id} with external_url.

curl -X PATCH https://app.getkleos.ai/v1/articles/ARTICLE_ID \
  -H "Authorization: Bearer YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_url": "https://www.example.com/blog/close-the-books-in-three-days"}'

The same thing by hand: open the article under Articles, paste the full https link under “Published it? Paste the link” and press Record as published. Only someone who can publish can do it, and only for approved articles. Either way, Kleos sends article.published and starts the Google index checks.

Prefer polling to webhooks? GET /v1/articles?status=approved (a daily schedule is plenty) lists what is ready and GET /v1/articles/{id} returns the text as body_md; then record each live link with the same PATCH. The two Markdown-file scripts below work that way.

Worked examples

Four ways to wire it up

Next.js or any Node site with a database or CMS

The endpoint you add in Kleos. It checks the signature with the Node sample above, answers at once, then creates (or updates) the post from article.approved and records the page's address with the PATCH. On article.published it asks your host to rebuild, or does whatever should happen once an article is live.

// app/api/kleos/route.ts: the endpoint you add under Settings → API → Webhooks, as https://yoursite.com/api/kleos
import { verifyKleos } from "@/lib/verify-kleos"; // the Node verification sample above, saved as lib/verify-kleos.js
import { upsertPost } from "@/lib/posts"; // your database or CMS: returns the page's public address
import { after } from "next/server";

export async function POST(req: Request) {
  const body = await req.text(); // the raw body, exactly as sent: don't parse and re-serialize before checking
  const headers: Record<string, string> = {};
  req.headers.forEach((value, name) => (headers[name] = value)); // lower-case names
  if (!verifyKleos(process.env.KLEOS_WEBHOOK_SECRET!, headers, body)) return new Response(null, { status: 401 });
  const event = JSON.parse(body);
  if (event.type === "article.approved") after(() => publish(event.data)); // answer first; the work runs after the response
  if (event.type === "article.published") after(() => fetch(process.env.DEPLOY_HOOK_URL!, { method: "POST" })); // or tell the team
  return new Response(null, { status: 204 }); // within 10 seconds
}

async function publish(article: any) {
  // Keyed on article.id: an article approved again after edits arrives again, and updates the same page.
  const url = await upsertPost({
    kleosId: article.id, slug: article.slug ?? article.id, title: article.title, html: article.body_html, excerpt: article.excerpt,
    seoTitle: article.meta_title ?? article.title, seoDescription: article.meta_description, heroImageUrl: article.hero_image?.url ?? null, heroImageAlt: article.hero_image?.alt ?? null, lang: article.language,
  });
  // Tell Kleos where it lives: it marks the article published, sends article.published and checks Google's index at 3, 7 and 14 days.
  const res = await fetch(`https://app.getkleos.ai/v1/articles/${article.id}`, {
    method: "PATCH",
    headers: { authorization: `Bearer ${process.env.KLEOS_API_KEY}`, "content-type": "application/json" }, // a key with write access
    body: JSON.stringify({ external_url: url }),
  });
  if (!res.ok) console.error("Kleos didn't record the link", res.status, await res.text());
}

The same receiver as a plain Express app:

import express from "express";
import { verifyKleos } from "./verify-kleos.js";

const app = express();
app.post("/webhooks/kleos", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  if (!verifyKleos(process.env.KLEOS_WEBHOOK_SECRET, req.headers, body)) return res.sendStatus(401);
  const event = JSON.parse(body);
  // Answer fast, then do the work. Use event.id to skip an event you have already handled.
  res.sendStatus(204);
  if (event.type === "article.approved") publish(event.data).catch(console.error);
});

// The article is the whole thing: title, slug, body_html (or body_md), excerpt, meta_title, meta_description, hero_image,
// faq, language. Create the page in your CMS, then tell Kleos where it lives: Kleos marks the article published, sends
// article.published to your other endpoints, and checks whether Google indexes the page at 3, 7 and 14 days.
async function publish(article) {
  const url = await createPage(article); // your CMS or database; the page must be live before the next line
  const res = await fetch(`https://app.getkleos.ai/v1/articles/${article.id}`, {
    method: "PATCH",
    headers: { authorization: `Bearer ${process.env.KLEOS_API_KEY}`, "content-type": "application/json" }, // a key with write access
    body: JSON.stringify({ external_url: url }),
  });
  if (!res.ok) throw new Error(`Kleos didn't record the link: ${res.status} ${await res.text()}`);
}

Zapier or Make: WordPress.com, HubSpot, Wix and others

No code: a Zapier or Make webhook trigger receives article.approved, your CMS's own Zapier or Make action creates the post from the event's fields, and one HTTP step records the live link in Kleos. Neither Zapier nor Make checks the signature, so keep the webhook address private.

Squarespace: it has no posting API, so neither route can create the page. Download the import file from the article's page (or all approved articles under Integrations → Squarespace) and import it under Settings → Import & export → Import → WordPress → Advanced. Then record the live link, in the app or with the PATCH, and article.published still fires for your other tools.

A static site (Next.js, Hugo, Jekyll): Markdown files in a Git repository, by polling

When the page only exists after a build, pull approved articles into content/blog as Markdown with front matter before the build, commit the files (or let your CI do it), and after the deploy record each page's address. The receiver above still works for a static site if your host can rebuild on demand; these scripts are for sites that would rather poll.

// pull-kleos-articles.mjs: approved articles → content/blog/<slug>.md. Node 18+, no packages.
// The polling alternative to article.approved: run it on a schedule (cron, GitHub Actions) or as the first step of your
// site's build. Needs a read API key. After the deploy, record each page's address (see record-kleos-links below).
import { access, mkdir, writeFile } from "node:fs/promises";

const API = "https://app.getkleos.ai/v1";
const KEY = process.env.KLEOS_API_KEY;         // a read key from Settings → API
const BUSINESS = process.env.KLEOS_BUSINESS_ID; // the business's id (GET /v1/products lists them)
const DIR = "content/blog";

async function get(path) {
  const res = await fetch(`${API}${path}`, { headers: { authorization: `Bearer ${KEY}` } });
  if (!res.ok) throw new Error(`${path}: ${res.status}`);
  return res.json();
}

await mkdir(DIR, { recursive: true });
let cursor = null;
do {
  const page = await get(`/articles?status=approved&product_id=${BUSINESS}&limit=50${cursor ? `&cursor=${cursor}` : ""}`);
  for (const a of page.data) {
    const file = `${DIR}/${a.slug ?? a.id}.md`;
    if (await access(file).then(() => true, () => false)) continue; // already pulled
    const full = await get(`/articles/${a.id}`); // the list has no text; this has body_md
    const front = [
      "---",
      `title: ${JSON.stringify(full.title)}`,
      `description: ${JSON.stringify(full.meta_description ?? "")}`,
      `seo_title: ${JSON.stringify(full.meta_title ?? full.title)}`,
      `kleos_id: ${full.id}`,
      `date: ${new Date().toISOString().slice(0, 10)}`,
      "---",
    ].join("\n");
    await writeFile(file, `${front}\n\n${full.body_md ?? ""}\n`);
    console.log(`wrote ${file}`);
  }
  cursor = page.next_cursor;
} while (cursor);

// record-kleos-links.mjs: run after the site is deployed. For each content/blog/<slug>.md with a kleos_id and no
// kleos_recorded line, PATCH the live address to Kleos (a key with write access), then mark the file so it isn't sent twice.
import { readdir, readFile, writeFile } from "node:fs/promises";

const KEY = process.env.KLEOS_API_KEY;     // a write key from Settings → API
const SITE = process.env.SITE_URL;         // https://www.example.com
const DIR = "content/blog";

for (const name of await readdir(DIR)) {
  const path = `${DIR}/${name}`;
  const text = await readFile(path, "utf8");
  const id = text.match(/^kleos_id: (\S+)/m)?.[1];
  if (!id || /^kleos_recorded: /m.test(text)) continue;
  const url = `${SITE}/blog/${name.replace(/\.md$/, "")}/`; // your site's address for the page
  const res = await fetch(`https://app.getkleos.ai/v1/articles/${id}`, {
    method: "PATCH", headers: { authorization: `Bearer ${KEY}`, "content-type": "application/json" }, body: JSON.stringify({ external_url: url }),
  });
  if (!res.ok) { console.error(`${url}: Kleos said ${res.status}`, await res.text()); continue; } // 422: the page isn't live yet, or the article isn't approved
  await writeFile(path, text.replace(/^---\n/, `---\nkleos_recorded: ${new Date().toISOString()}\n`));
  console.log(`recorded ${url}`);
}

Python: a Flask receiver, or a Hugo or Jekyll pull

The receiver, using the Python verification sample above: it creates the page from article.approved and records the live link.

import json, os, urllib.request
from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/kleos")
def kleos():
    body = request.get_data(as_text=True)
    headers = {k.lower(): v for k, v in request.headers.items()}
    if not verify_kleos(os.environ["KLEOS_WEBHOOK_SECRET"], headers, body):
        return "", 401
    event = json.loads(body)
    # Use event["id"] to skip an event you have already handled; do slow work after answering.
    if event["type"] == "article.approved":
        publish(event["data"])
    return "", 204

def publish(article):
    """Create the page from the article (title, body_html or body_md, excerpt, meta_title, meta_description, hero_image,
    faq), then tell Kleos where it lives: it becomes published, article.published goes out, Google's index is checked."""
    url = create_page(article)  # your CMS; the page must be live before the request below
    req = urllib.request.Request(
        f"https://app.getkleos.ai/v1/articles/{article['id']}",
        method="PATCH",
        data=json.dumps({"external_url": url}).encode(),
        headers={"Authorization": f"Bearer {os.environ['KLEOS_API_KEY']}", "Content-Type": "application/json"},  # a key with write access
    )
    with urllib.request.urlopen(req, timeout=30) as res:
        return json.load(res)

And the polling shape with the standard library only: approved articles become files under content/posts (Hugo) or _posts (Jekyll), the site builds them, and the curl line above (or the Node record script) records the links after the deploy.

# pull_kleos_articles.py: approved articles → content/posts/<slug>.md. Python 3.9+, standard library only.
# The polling alternative to article.approved: run it on a schedule or before the site builds. Needs a read API key.
# After the deploy, record each page's address with PATCH /v1/articles/{id} (the curl line above, or the Node script).
import json, os, urllib.request
from datetime import date

API = "https://app.getkleos.ai/v1"
KEY = os.environ["KLEOS_API_KEY"]           # a read key from Settings → API
BUSINESS = os.environ["KLEOS_BUSINESS_ID"]  # the business's id (GET /v1/products lists them)
DIR = "content/posts"                        # Hugo. Jekyll: "_posts", and put the date first in the file name.

def get(path):
    req = urllib.request.Request(f"{API}{path}", headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=30) as res:
        return json.load(res)

os.makedirs(DIR, exist_ok=True)
cursor = None
while True:
    page = get(f"/articles?status=approved&product_id={BUSINESS}&limit=50" + (f"&cursor={cursor}" if cursor else ""))
    for a in page["data"]:
        path = os.path.join(DIR, f"{a['slug'] or a['id']}.md")
        if os.path.exists(path):
            continue  # already pulled
        full = get(f"/articles/{a['id']}")  # the list has no text; this has body_md
        front = "\n".join([
            "---",
            f"title: {json.dumps(full['title'])}",
            f"description: {json.dumps(full.get('meta_description') or '')}",
            f"kleos_id: {full['id']}",
            f"date: {date.today().isoformat()}",
            "draft: false",
            "---",
        ])
        with open(path, "w", encoding="utf-8") as f:
            f.write(front + "\n\n" + (full.get("body_md") or "") + "\n")
        print("wrote", path)
    cursor = page.get("next_cursor")
    if not cursor:
        break