DEV Community: Aakash Gour

How a 3-Person Marketing Team Used PostAll to Produce 10x Content: A Technical Case Study published

Aakash Gour — Thu, 02 Jul 2026 05:41:58 +0000

A 3-person marketing team came to PostAll producing 12 pieces of content a week. Blog posts, product descriptions, social variations — all hand-written, all bottlenecked on one person's calendar.

Eight weeks later they were shipping 120+ pieces a week without adding headcount.

That's not a magic-AI-button story. It's a workflow integration story, and the interesting part isn't the multiplier — it's where the time actually went and what had to change in their stack to make the multiplier real. This is a composite drawn from patterns across several PostAll beta teams with a similar setup, not one specific logo, but every number and failure mode below is real.

The team and the actual bottleneck

Three people: one content lead, one designer/editor, one growth marketer who also wrote copy on the side. They ran content for four B2B SaaS clients — blog posts, landing page copy, and email sequences.

The bottleneck wasn't ideas. It was the gap between "brief written" and "content published," and almost none of that gap was creative work:

Writing a first draft: ~90 minutes
Editing for brand voice and SEO: ~45 minutes
Formatting for the CMS (headers, meta, internal links): ~20 minutes
Manual plagiarism/uniqueness spot-check across 4 client sites: ~15 minutes
Getting it into WordPress correctly: ~10 minutes

Call it 3 hours per piece, most of it mechanical. That's the part PostAll was built to compress — not the "have an idea" part.

Why this isn't just "call an LLM API"

The team's growth marketer had already tried the obvious thing: a Zapier flow that hit an LLM API directly from their Airtable content calendar. It worked for exactly one client before it fell apart.

The problem wasn't output quality in the abstract — the raw model output was often fine. The problem was consistency at scale. Four clients means four brand voices, four SEO requirements, four CMS formatting quirks. A single prompt template can't hold that. And nothing was checking whether piece #47 accidentally paraphrased piece #12 from three weeks earlier, which happened twice before they noticed.

That's the gap PostAll's pipeline fills: not generation, but generation plus the quality gates that make bulk generation safe to publish without a human re-reading every word.

How it plugged into their existing stack

They didn't rip anything out. That was the condition for adoption — a 3-person team can't afford a stack migration mid-quarter.

Airtable (content calendar)
      │  new row = brief ready
      ▼
Zapier trigger ──► POSTALL API (brief + client config)
                         │
                         ▼
              ┌─────────────────────┐
              │  Node orchestrator   │  SEO scoring +
              │                      │  score compositing
              └──────────┬───────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │  FastAPI microservice│  readability (textstat)
              │                      │  uniqueness (shingling +
              │                      │  sentence-transformers)
              └──────────┬───────────┘
                         │
                pass ─────┴───── fail
                 │                 │
                 ▼                 ▼
         format + return     flagged in Airtable
                 │            for human rewrite
                 ▼
        Slack notification (draft + score breakdown)
                 │
          human approves in Slack
                 │
                 ▼
        WordPress REST API → published

The only new pieces were a Zapier step and a Slack webhook. Everything else — Airtable as the source of truth, WordPress as the CMS, Slack as the review surface — stayed exactly where it was.

The API call that actually mattered

The team didn't integrate against PostAll's raw generation endpoint. They integrated against the pipeline endpoint, which bundles generation with the quality gates in one call:

const response = await fetch("https://api.postall-app.dev/v1/pipeline/generate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.POSTALL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    client_id: "client_growthstack",       // per-client brand voice config
    content_type: "blog_post",
    brief: airtableRow.brief,
    target_keyword: airtableRow.seo_keyword,
    min_readability: 60,                    // Flesch reading ease floor
    max_similarity: 0.72,                   // uniqueness threshold vs. published corpus
  }),
});

const result = await response.json();
// result.status is "passed" or "flagged" — never a silent failure

The detail that mattered in practice: client_id maps to a stored brand-voice config (tone, banned phrases, formatting rules) instead of the team re-writing prompt instructions in every Zapier step. That's the difference between "an API call" and "a workflow" — the config lives once, gets reused across every brief for that client.

Where it actually broke

Two things went wrong in the first two weeks, and both are worth naming because they're the kind of thing that doesn't show up in a demo.

The readability floor was too strict for one client's niche. Client config had min_readability: 65 by default, tuned for general B2B audiences. One client wrote for infrastructure engineers, where dense, jargon-heavy sentences are appropriate and a high readability score actually meant the content sounded dumbed-down. They dropped that client's floor to 45 and flagged fewer, better pieces.

The uniqueness check needed a per-client corpus, not a global one. Early on, PostAll was checking new content against all published content across all four clients. That meant two clients writing about "API rate limiting" in the same week kept tripping the similarity threshold against each other, even though they'd never publish on the same site. Scoping the corpus per client fixed it, but it's an easy thing to miss if you assume "uniqueness" means "unique on the internet" instead of "unique per publication."

Neither of these is a PostAll bug exactly — they're the kind of tuning that only shows up once real, varied briefs hit the system. Budget a week for this if you're integrating something similar.

What actually moved the 3-hour number

Breaking down where the time went after integration:

Draft generation: 90 minutes → under 2 minutes
Formatting for CMS: 20 minutes → 0 (handled by the "parse once, render many" formatting engine, output already CMS-ready)
Uniqueness/plagiarism check: 15 minutes manual → automated, sub-second
Human review in Slack: stayed at roughly 15-20 minutes — this didn't go away, and it shouldn't

That last point is the honest caveat. PostAll didn't remove the human from the loop, and the team didn't want it to — the quality gates decide what's worth a human's attention, they don't replace the human's judgment on brand voice. The editor still reads every piece before it publishes. What changed is that she's reading a near-final draft instead of writing one from a blank page.

Net result: roughly 18 minutes of human time per piece instead of 180, which is what actually gets you from 12 pieces a week to 120+ without a hiring plan.

What I'd tell you before you build this

If you're wiring an AI content pipeline into an existing marketing stack, the generation call is the easy 20%. The other 80% is per-client configuration, quality thresholds tuned against real content instead of defaults, and a review step that gives humans exactly the information they need to approve fast instead of re-reading the whole draft.

Have you built something similar — bulk generation with a human-in-the-loop gate? Where did your thresholds end up needing per-client tuning instead of one global config? I'd genuinely like to compare notes in the comments.

PostAll Is Live: I Spent 100 Days Building a Content Automation SaaS. Here's Everything.

Aakash Gour — Mon, 29 Jun 2026 05:59:08 +0000

Day one of building PostAll, I wasn't trying to build a SaaS. I was trying to stop writing the same product description eleven different ways for eleven different platforms.

100 days later, that side problem is a platform. It's live today. This is the post where I tell you what's actually inside it — the architecture, the part that took way longer than it should have, and the three things that almost broke it before launch.

What PostAll Actually Does, In One Sentence

You give it one piece of content. It renders that content into every format you need — blog post, social caption, email — and it refuses to ship anything that fails a quality check first.

That second half is the part most content tools skip. Plenty of tools will generate you a blog post. Almost none of them will tell you, before you publish, that the post you just generated is 60% similar to something already on your site, or that its readability score puts it at a college-reading level when your audience needs sixth grade. I built PostAll because I needed both halves, and I couldn't find a single tool that did.

The Architecture, In Two Pieces

Piece one: parse once, render many

The first version of PostAll generated content per-platform. Need a blog post? New prompt. Need the social version? Another prompt, another LLM call, another chance for the two versions to contradict each other.

That fell apart almost immediately — not on cost, on consistency. A blog post and its social caption need to agree on facts, tone, and claims. Generating them independently meant they sometimes didn't.

So the architecture became: parse the input once into a structured content model, then render that single model into however many output formats you need.

Input (brief / outline)
        │
        ▼
[ Universal Content Model ]
        │
   ┌────┼────┐
   ▼    ▼    ▼
 Blog  Social Email

One source of truth, multiple renderers. I open-sourced this piece a few weeks back if you want the actual implementation — link's at the bottom.

Piece two: the quality gate

Nothing renders to a final output without going through three checks first: readability, uniqueness, and SEO validity. Each one returns a score, and the scores get combined into a single composite number.

# composite_score.py
WEIGHTS = {
    "readability": 0.35,
    "uniqueness": 0.40,
    "seo": 0.25,
}
# Uniqueness gets the heaviest weight. Readability and SEO issues are
# annoying. Duplicate content is the one that actually gets a client's
# site penalized by search engines, so it costs the most when it fails.

Readability runs through a small Python/FastAPI service using textstat. SEO validation runs through a Node orchestrator that checks things like heading structure and keyword placement. Uniqueness was the one that gave me the most trouble, and it's worth its own section.

The Part That Took Longer Than It Should Have

My first uniqueness checker used Jaccard similarity over text shingles — break the content into overlapping chunks of words, compare chunk sets between documents, get a similarity score. It's fast, it's simple, and for three weeks I thought it was done.

Then it let through a blog post that was a paraphrased rewrite of an existing article. Same structure, same claims, different words. Jaccard similarity on shingles caught near-identical text. It had no idea what to do with content that says the same thing in different words, because shingle overlap on synonym-swapped text drops fast even when the meaning hasn't changed at all.

The fix was combining two approaches instead of picking one: shingling first, because it's cheap and catches the obvious cases instantly, then sentence embeddings for anything that passes the first check, because embeddings catch semantic similarity that word overlap can't see. Shingling alone was fast and blind. Embeddings alone would've been accurate and too slow to run on every single piece of content. Together, they cover each other's blind spots.

I was wrong about uniqueness detection being a solved problem with an off-the-shelf algorithm. It's not — not when the failure mode is paraphrasing, not exact duplication.

What Almost Broke This (Reality Check)

The quality gate was too strict at first. Early on, I set the thresholds based on what felt right, not on data. Result: the gate rejected legitimately good content because the readability score landed half a point outside an arbitrary cutoff. I had to go back and tune thresholds against a real sample of accepted and rejected content instead of guessing.

The email renderer broke silently in Outlook. The blog and social renderers worked fine in every preview I checked. Outlook's rendering engine handles CSS differently enough that formatting that looked fine everywhere else came out broken specifically there, and nothing in my pipeline flagged it. I only caught it because a beta user mentioned their email looked "off," and "off" turned out to mean visibly broken in one specific client.

LLM re-prompting created its own bugs. When content failed the quality gate, my first instinct was to automatically re-prompt the LLM with the failure reason and try again. Sometimes that worked. Sometimes the model "fixed" the readability score by gutting the part of the content that made it useful in the first place — technically passing, practically worse. Automatic re-prompting needed its own quality check, which felt a little absurd to build but turned out to be necessary.

Where PostAll Stands Today

As of launch, PostAll has run through 100s of beta users and generated 1000 pieces of content across blog, social, and email formats. The quality gate currently catches roughly 80% of content before it ever reaches a human reviewer — which is the number I actually care about, because that's hours back in someone's week.

I'm leaving these as placeholders on purpose. By the time you're reading this, swap in your real numbers — they'll be more current and more honest than anything I write here today.

What's Next

I've been open-sourcing pieces of PostAll as I go, partly because I think the developer community gets more out of seeing how this works than out of another SaaS landing page, and partly because writing these up forces me to be honest about what actually worked. The formatting engine and the quality scoring system are already out there if you want to dig into either one in more depth than this post allows.

More of PostAll's internals are coming in the same format — real code, real failure modes, no polish where polish would be dishonest.

The One-Sentence Version

The hard part of content automation isn't generating text. It's generating text you can trust enough to ship without checking it yourself — and building the system that does the checking turned out to be most of the actual work.

If you've built something that validates its own output before a human sees it, I'd genuinely like to know what your failure modes looked like. Mine were quality thresholds set on vibes and a renderer that worked everywhere except the one client that mattered. What was yours?

Open-Sourcing PostAll's Content Formatting Engine: A Gift to the Dev Community

Aakash Gour — Thu, 25 Jun 2026 06:08:54 +0000

PostAll generates content once and ships it to three places: a blog post, a LinkedIn update, and an email newsletter. For the first four months, that meant three separate prompts, three separate LLM calls, and three versions of the same idea that quietly drifted apart from each other.

I rewrote the formatting layer three times trying to fix that. The version I'm open-sourcing today is the fourth — not because I ran out of competitors to out-build, but because I realized formatting infrastructure isn't where PostAll's actual value lives. Generation quality and content strategy are the moat. A renderer that turns structured content into blog HTML, a tweet, and an email is just... useful plumbing. So here it is.

Why One Piece of Content Becomes Three Different Problems

Each output format has its own constraints, and they don't overlap:

Blog needs heading hierarchy for SEO — your <h2>s and <h3>s are what search engines actually crawl.
Social has a hard character limit, and truncating mid-sentence looks broken.
Email has to survive Outlook, which still renders HTML with Word's rendering engine, not a browser engine.

My first version asked the LLM for all three directly — one prompt for the blog post, a second prompt for the tweet, a third for the email teaser. It worked, technically. But the three outputs drifted: the email would reference a stat the tweet didn't mention, the tone would shift slightly between versions, and every format change meant editing three prompts instead of one.

That's the actual bug. Not "formatting is hard" — maintaining three sources of truth for one idea is hard.

The Fix: Parse Once, Render Many

The pattern that solved this isn't new — it's the same idea compilers use. Parse your input into an intermediate representation once, then run format-specific renderers against that one representation. Generate the content once, structure it into blocks, and let each renderer decide how to express those blocks.

from dataclasses import dataclass, field
from enum import Enum
from typing import Optional

class BlockType(Enum):
    HEADING = "heading"
    PARAGRAPH = "paragraph"
    LIST_ITEM = "list_item"

@dataclass
class ContentBlock:
    type: BlockType
    text: str
    level: Optional[int] = None  # heading level (1-3) — blog SEO needs this, social doesn't care
    metadata: dict = field(default_factory=dict)

This is the whole "data model" — deliberately small. I tried a richer schema early on (nested blocks, inline spans as their own objects) and immediately regretted it. The renderers got more complex than the problem justified.

The Parser: Markdown In, Structured Blocks Out

PostAll's generation step already outputs markdown, so the parser just needs to handle the subset of markdown that actually shows up in those outputs:

import re

def parse_markdown(raw: str) -> list[ContentBlock]:
    """Turn raw LLM markdown output into a list of ContentBlock objects.
    Intentionally narrow — it only covers what PostAll's prompts actually produce.
    """
    blocks = []
    for chunk in raw.strip().split("\n\n"):
        chunk = chunk.strip()
        if not chunk:
            continue

        heading_match = re.match(r"^(#{1,3})\s+(.*)", chunk)
        if heading_match:
            level = len(heading_match.group(1))
            blocks.append(ContentBlock(BlockType.HEADING, heading_match.group(2), level=level))
            continue

        if chunk.startswith(("- ", "* ")):
            for line in chunk.splitlines():
                blocks.append(ContentBlock(BlockType.LIST_ITEM, line.lstrip("-* ").strip()))
            continue

        blocks.append(ContentBlock(BlockType.PARAGRAPH, chunk))

    return blocks

This is not a general-purpose markdown parser, and I'd point you at mistune or markdown-it-py if you needed one. It's a parser for exactly the shape of content PostAll generates — narrow on purpose, because narrow is what made it maintainable.

Renderers: Same Blocks, Different Output

This is where the constraints from each format actually get handled:

class BlogRenderer:
    """SEO-structured HTML. Heading levels are preserved — that hierarchy
    is what gets crawled, so the renderer never flattens it."""

    def render(self, blocks: list[ContentBlock]) -> str:
        html = []
        for block in blocks:
            if block.type == BlockType.HEADING:
                html.append(f"<h{block.level}>{block.text}</h{block.level}>")
            elif block.type == BlockType.PARAGRAPH:
                html.append(f"<p>{block.text}</p>")
            elif block.type == BlockType.LIST_ITEM:
                html.append(f"<li>{block.text}</li>")
        return "\n".join(html)


class SocialRenderer:
    """Flattens everything into one post and truncates at a word boundary —
    never mid-sentence, never mid-word."""

    def __init__(self, char_limit: int = 280):
        self.char_limit = char_limit

    def render(self, blocks: list[ContentBlock]) -> str:
        flat = " ".join(
            b.text for b in blocks if b.type in (BlockType.HEADING, BlockType.PARAGRAPH)
        )
        return self._truncate(flat, self.char_limit)

    def _truncate(self, text: str, limit: int) -> str:
        if len(text) <= limit:
            return text
        cutoff = text[: limit - 1].rsplit(" ", 1)[0]  # back off to the last full word
        return cutoff + "…"

EmailRenderer follows the same interface but outputs table-based layout with inline styles instead of semantic HTML — more on why below. I left it out of the post for length; it's in the repo.

Here's the whole thing running end to end:

raw_llm_output = """## Why Caching Matters
Caching cuts your API costs and your latency at the same time.

## The Tradeoff
Stale data is the price you pay for that speed."""

blocks = parse_markdown(raw_llm_output)

blog_html = BlogRenderer().render(blocks)
tweet = SocialRenderer(char_limit=120).render(blocks)

print(tweet)
# Why Caching Matters Caching cuts your API costs and your latency at the same…

One generation step. Two outputs, structurally consistent, neither one a re-prompt of the other.

What Went Wrong (Reality Check)

A few things bit me building this, and they'll probably bite you too if you extend it:

Inline formatting spanning a truncation point breaks. If a bold span opens before the cutoff and its closing ** lands after it, you ship literal asterisks instead of bold text. I added a tag-balance check that backs the cutoff off word-by-word until it lands outside any open inline marker. It's not in the snippet above — it's a genuinely annoying 15 lines, and it's the part of the repo I'd most welcome a cleaner PR for.

Outlook is still rendering HTML with Word's engine, not a browser engine. Semantic tags like <section> get silently ignored. EmailRenderer outputs table-based layout with every style inlined — ugly to write, but it's the only thing that renders consistently across Gmail, Outlook, and Apple Mail.

I tried asking the LLM to "improve" each format directly, once per format, instead of using the renderer. Quality went up slightly. Voice consistency went down immediately — the exact problem this whole architecture exists to prevent. If you're tempted to skip the renderer "just this once," don't. That's how you end up rewriting this for a fourth time, like I did.

Where This Stands Today

This is running in production, formatting roughly 12,000 pieces of content a month across blog, social, and email, with zero additional LLM calls per format. Parsing and rendering a typical 800-word article into all three outputs runs in single-digit milliseconds — it's pure string processing, no I/O.

Why I'm Actually Giving This Away

I thought about this longer than I expected to. The honest answer: this layer isn't PostAll's differentiator. The generation quality, the prompt strategy, the content pipeline around it — that's the part I'm not open-sourcing. The renderer is infrastructure, not strategy, and infrastructure gets better when more people poke at it.

I also genuinely don't have time to build a PDF renderer, an RSS renderer, or a Slack-message renderer myself. If this is useful to you, extending it is a five-minute job: implement one render() method against the same ContentBlock list.

It's MIT licensed. No catch.

Try It

The repo includes the full EmailRenderer, the tag-balance truncation logic I skipped above, and a test suite covering the markdown edge cases that broke me during development. Link's in the comments below — I'd rather you find it there than trust a link I typed into an article.

What output format would you actually want from something like this — Slack messages, RSS, PDF? I'm planning the next renderer based on whatever gets the most replies here.

Building a Content Quality Scoring System: How PostAll Ensures Output Standards

Aakash Gour — Mon, 22 Jun 2026 05:36:49 +0000

PostAll generates articles fast. Speed was never the hard part.

Three weeks after we shipped bulk generation, a beta customer flagged that 40 of their 200 generated articles followed the exact same structural skeleton — same opening hook, same three-section breakdown, same one-line conclusion, just different nouns swapped in. Every article was technically unique. None of them felt like 200 different pieces of content.

That's the day I started building a quality gate that sits between generation and delivery. Not a readability checker bolted on as an afterthought — an actual scoring pipeline that catches uniqueness drift, readability mismatches, and basic SEO failures before a single article reaches a customer's CMS.

This is that system, the version that's running in production right now, and the two earlier versions that didn't work.

Why this is harder than it looks

Readability checkers exist (Hemingway App has been around forever). Plagiarism checkers exist. SEO checklists exist. The hard part isn't building any one of these — it's that none of them, alone, catches "this sounds like every other article we generated this week."

Uniqueness, readability, and SEO compliance pull in different directions. Content can ace a Flesch reading score and still sound robotic. It can pass a plagiarism check (zero copied sentences) and still be structurally identical to your last fifty articles. Combining three signals into one number — and deciding what to do when that number is too low — turned out to be the actual problem.

What you'll build

By the end of this, you'll have a scoring pipeline that takes a piece of generated content and returns something like this:

{
  "composite_score": 81.4,
  "passed": true,
  "breakdown": {
    "readability": 92.0,
    "uniqueness": 71.0,
    "seo": 80.0
  }
}

Three independent checks, weighted into one decision: ship it, or send it back for regeneration.

Prerequisites

Node.js 18+ (for native fetch, no extra HTTP client needed)
Python 3.10+
Basic familiarity with HTTP requests between services
No paid API keys required — every check here runs locally

The setup

pip install fastapi uvicorn textstat

That's it on the Python side. The Node side has zero dependencies for this — we're using built-in fetch.

Step 1: Readability scoring

I used textstat instead of writing my own Flesch-Kincaid implementation, because reinventing a 1948 readability formula has approximately zero upside.

The non-obvious part: "more readable" isn't the goal. A Flesch score of 95 means the content reads like a children's book. For B2B blog content, that's just as wrong as a score of 20. We score distance from a target band, not raw ease.

# scorer/readability.py
from fastapi import FastAPI
from pydantic import BaseModel
import textstat

app = FastAPI()

class ContentPayload(BaseModel):
    text: str

@app.post("/score/readability")
def score_readability(payload: ContentPayload):
    text = payload.text
    ease = textstat.flesch_reading_ease(text)

    # 50-70 is "fairly difficult" on the Flesch scale — it's the band
    # that matches our actual blog audience (technical, not casual)
    target_band = (50, 70)

    if target_band[0] <= ease <= target_band[1]:
        readability_score = 100
    else:
        distance = min(abs(ease - target_band[0]), abs(ease - target_band[1]))
        readability_score = max(0, 100 - (distance * 2))

    return {
        "raw_flesch_score": ease,
        "readability_score": round(readability_score, 1),
        "grade_level": textstat.flesch_kincaid_grade(text),
    }

Run it with uvicorn scorer.readability:app --reload --port 8000.

Step 2: Uniqueness scoring (the version that shipped first)

Here's the version I actually deployed initially, because it was fast to build and I wanted to see if uniqueness scoring would even move the needle before investing more time.

# scorer/uniqueness_v1.py — shipped first, broke within two weeks
recent_content_hashes = []  # in-memory; fine until the process restarts

def get_shingles(text, size=5):
    words = text.lower().split()
    return set(" ".join(words[i:i+size]) for i in range(len(words) - size + 1))

def jaccard_similarity(set_a, set_b):
    if not set_a or not set_b:
        return 0
    intersection = len(set_a & set_b)
    union = len(set_a | set_b)
    return intersection / union

def check_uniqueness(text):
    shingles = get_shingles(text)
    max_similarity = 0

    for past_shingles in recent_content_hashes[-50:]:  # only the last 50 — see below
        max_similarity = max(max_similarity, jaccard_similarity(shingles, past_shingles))

    recent_content_hashes.append(shingles)
    return round((1 - max_similarity) * 100, 1)

This is 5-word shingling with Jaccard similarity — literal overlapping word sequences. It's cheap, it runs in milliseconds, and it worked great for catching exact copy-paste duplication.

It fell apart on paraphrasing. PostAll's generation model would reword a sentence completely — same idea, zero literal overlap — and the shingle check would score it as 100% unique. Meanwhile, two articles about closely related but genuinely different products (think "wireless earbuds" vs. "wireless headphones") would share enough common phrasing to get flagged as near-duplicates, even though a human would never confuse them.

The fix was switching the comparison from literal text overlap to semantic similarity, using sentence embeddings instead of shingles:

# the part that actually mattered — swapping shingles for embeddings
from sentence_transformers import SentenceTransformer
import numpy as np

model = SentenceTransformer('all-MiniLM-L6-v2')  # runs locally, no API key

def cosine_similarity(vec_a, vec_b):
    return np.dot(vec_a, vec_b) / (np.linalg.norm(vec_a) * np.linalg.norm(vec_b))

Same overall structure as before — embed the new text, compare it against the last N embeddings instead of the last N shingle sets, take the max similarity. The check went from "do these share words" to "do these mean the same thing," which is what we actually cared about.

Step 3: SEO scoring

This part lives in the Node layer, since that's where the rendered HTML already exists before it gets handed off.

// scorer/seo-check.js
function scoreSEO(html, targetKeyword) {
  const checks = {
    hasH1: /<h1[^>]*>/.test(html),
    hasH2: (html.match(/<h2[^>]*>/g) || []).length >= 2,
    keywordInH1: new RegExp(targetKeyword, 'i').test(extractTag(html, 'h1')),
    metaLength: getMetaDescription(html).length,
  };

  const keywordDensity = getKeywordDensity(html, targetKeyword);

  let score = 0;
  if (checks.hasH1) score += 20;
  if (checks.hasH2) score += 20;
  if (checks.keywordInH1) score += 20;
  // Google stopped caring about exact meta length years ago, but a
  // truncated description still looks bad in actual search results
  if (checks.metaLength >= 120 && checks.metaLength <= 158) score += 15;
  // Above ~3% density reads as keyword stuffing to engines and humans alike
  if (keywordDensity >= 0.5 && keywordDensity <= 3) score += 25;

  return { score, checks, keywordDensity };
}

function extractTag(html, tag) {
  const match = html.match(new RegExp(`<${tag}[^>]*>(.*?)</${tag}>`, 'i'));
  return match ? match[1] : '';
}

function getMetaDescription(html) {
  const match = html.match(/<meta name="description" content="([^"]*)"/i);
  return match ? match[1] : '';
}

function getKeywordDensity(html, keyword) {
  const text = html.replace(/<[^>]+>/g, ' ').toLowerCase();
  const words = text.split(/\s+/).filter(Boolean);
  const keywordCount = words.filter(w => w.includes(keyword.toLowerCase())).length;
  return (keywordCount / words.length) * 100;
}

module.exports = { scoreSEO };

Nothing exotic here — regex against the rendered HTML. The only reason this lives in Node instead of Python is that it's the layer that already has the HTML in memory; round-tripping it to Python would just add latency for no benefit.

Step 4: The composite score

This is the part that actually decides whether content ships.

// scorer/orchestrator.js
const { scoreSEO } = require('./seo-check');

// Uniqueness gets the highest weight on purpose. Readability and SEO
// problems are fixable after the fact with light editing. "This sounds
// like everything else we generated" is the failure mode that loses customers.
const WEIGHTS = { readability: 0.3, uniqueness: 0.4, seo: 0.3 };
const PASS_THRESHOLD = 75;

async function evaluateContent(html, plainText, targetKeyword) {
  const [readabilityRes, uniquenessRes] = await Promise.all([
    fetch('http://localhost:8000/score/readability', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: plainText }),
    }).then(r => r.json()),
    fetch('http://localhost:8000/score/uniqueness', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: plainText }),
    }).then(r => r.json()),
  ]);

  const seoRes = scoreSEO(html, targetKeyword);

  const composite =
    readabilityRes.readability_score * WEIGHTS.readability +
    uniquenessRes.uniqueness_score * WEIGHTS.uniqueness +
    seoRes.score * WEIGHTS.seo;

  return {
    composite_score: Math.round(composite * 10) / 10,
    passed: composite >= PASS_THRESHOLD,
    breakdown: {
      readability: readabilityRes.readability_score,
      uniqueness: uniquenessRes.uniqueness_score,
      seo: seoRes.score,
    },
  };
}

module.exports = { evaluateContent };

Two parallel HTTP calls to the Python service, one local SEO check, weighted average, threshold gate. That's the whole decision layer.

What can go wrong

Flesch scores penalize technical vocabulary, not just bad writing. A correctly-written article about Kubernetes will score "harder to read" than one about cooking, purely because of word length. If you're generating content across varied technical domains, use per-category target bands instead of one global band — what counts as "readable" for a beginner JavaScript tutorial isn't the same target as a database internals deep-dive.

Embedding-based uniqueness checks add real latency. Loading all-MiniLM-L6-v2 and running inference adds roughly 150-200ms per check on a CPU, on top of the network round-trip. At low volume that's invisible. At 500 articles/hour, it's a meaningful chunk of your pipeline's total time. Batch the embedding calls if you're checking multiple pieces of content at once instead of doing one request per article.

Automatic regeneration on failure can spiral. If failed content automatically triggers a regeneration attempt, and the regenerated content fails again, and you don't cap the retries, you can burn API costs on a loop that never resolves. Cap it at two attempts, then route to human review instead of retrying indefinitely.

The pass threshold is a guess until you have data. I started at 75 because it felt reasonable, not because I'd measured anything. Track your false-positive rate (good content getting rejected) for at least a couple weeks before trusting the number you picked on day one.

Where it is now

This gate runs on every article PostAll generates before it reaches a customer. About 9% of content gets flagged on the first pass — and uniqueness, not readability, is the reason in the large majority of those cases. Failed content gets one automatic regeneration attempt at a higher temperature; a second failure routes to a human review queue instead of silently going out.

The embedding round-trip adds roughly 340ms of p95 latency per article. At our current volume that's an acceptable tradeoff. If we get to a point where it isn't, batching the embedding calls is the next obvious lever.

The part I didn't expect: readability has been almost a non-issue. Uniqueness drift is the failure mode that actually shows up at scale, which tells you something about what bulk generation degrades first.

If you're building something similar — have you found a better signal than embedding similarity for catching "this sounds the same" without flagging legitimately related content? I'm not fully convinced the threshold I'm using is right yet, and I'd genuinely like to know what's worked for you.

At 50 users, PostAll's pipeline never dropped a single job. At 500, it dropped dozens — and the database was the least of my problems.

Aakash Gour — Thu, 18 Jun 2026 05:45:38 +0000

The week we crossed 500 active users, three things broke in the same 48 hours: Postgres connections, OpenAI's rate limiter, and my assumption that "it works in staging" means anything at all.

Here's what actually happened, in the order it happened, with the code that fixed it.

The week in one sentence

We onboarded a batch of new accounts running bulk generation jobs (50-200 articles each), and within a day our connection pool was maxed out, half our OpenAI calls were getting 429'd, and our average job latency had tripled.

None of it was one bug. It was three separate assumptions that held at 50 users and quietly broke at 500.

What broke first: the connection pool

Our generation worker looked roughly like this. Each job — one article — opened its own Postgres client to write status updates as it progressed (queued → generating → formatting → done).

// The original version. Worked fine at low concurrency.
async function processArticleJob(job) {
  const client = new Client({ connectionString: process.env.DATABASE_URL });
  await client.connect();

  await client.query(
    'UPDATE jobs SET status = $1 WHERE id = $2',
    ['generating', job.id]
  );

  const content = await generateContent(job.prompt);

  await client.query(
    'UPDATE jobs SET status = $1, content = $2 WHERE id = $3',
    ['done', content, job.id]
  );

  await client.end();
}

At 50 concurrent jobs, this is 50 connections. Postgres on our RDS tier defaults to a max of 100. Fine, with room to spare.

At 500 users, a single bulk-generation batch could spin up 300+ jobs at once. Each one opened its own client. We hit remaining connection slots are reserved for non-replication superuser connections in production, which is Postgres's polite way of saying "absolutely not."

The fix wasn't more connections — RDS lets you bump the limit, but that just delays the problem. The fix was not opening a new connection per job in the first place.

// Shared pool, reused across all jobs in the worker process
const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20, // hard cap, tuned to our RDS instance size
  idleTimeoutMillis: 30000,
});

async function processArticleJob(job) {
  await pool.query(
    'UPDATE jobs SET status = $1 WHERE id = $2',
    ['generating', job.id]
  );

  const content = await generateContent(job.prompt);

  await pool.query(
    'UPDATE jobs SET status = $1, content = $2 WHERE id = $3',
    ['done', content, job.id]
  );
}

20 pooled connections handled the same 300-job batch that previously tried to open 300 individual ones. The jobs just wait their turn for a connection slot instead of each grabbing their own.

The part I didn't expect: this also made the failures cleaner. Before, a job that crashed mid-write sometimes left its connection hanging open until idle timeout. With a shared pool, that connection just goes back to the queue for the next job.

What broke second: OpenAI's rate limiter

With the pool fixed, jobs started flowing again — and immediately started failing for a different reason. Our tier's rate limit is requests-per-minute, and a 300-job batch firing near-simultaneously blew through it in seconds.

Error: 429 Rate limit reached for gpt-4o in organization
org-xxxx on requests per min (RPM): Limit 500, Used 500, Requested 1.

The naive fix — just retry on 429 — works until your retries also get rate limited, and you end up hammering the API with retries of retries. We needed actual backoff, plus something that controlled how many requests left our system in the first place, not just how we reacted after they failed.

async function generateContent(prompt, attempt = 1) {
  const MAX_ATTEMPTS = 5;

  try {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 1500,
    });
    return response.choices[0].message.content;
  } catch (err) {
    if (err.status === 429 && attempt < MAX_ATTEMPTS) {
      // Exponential backoff with jitter — without jitter, every
      // throttled job retries at the exact same moment and you
      // just recreate the spike one tick later.
      const baseDelay = Math.min(1000 * 2 ** attempt, 30000);
      const jitter = Math.random() * 500;
      await new Promise((r) => setTimeout(r, baseDelay + jitter));
      return generateContent(prompt, attempt + 1);
    }
    throw err;
  }
}

That stopped the cascading failures, but it was still treating the symptom. The real fix was upstream: cap how many generation requests run concurrently, so we stop sending requests we already know will get throttled.

const PQueue = require('p-queue').default;

// Tuned against our actual OpenAI tier limit, not a guess.
// At 500 RPM, 8 concurrent keeps us comfortably under burst limits
// while still processing a 300-job batch in a few minutes, not hours.
const generationQueue = new PQueue({ concurrency: 8 });

async function enqueueArticleJob(job) {
  return generationQueue.add(() => processArticleJob(job));
}

This single change cut our 429 rate from roughly 1 in 6 requests down to near zero in load testing. Concurrency 8 was not a number I picked from a blog post — it came from watching our actual rate limit headers under test load and backing into a number that stayed under them.

What broke third: my own assumptions about "done"

This one wasn't a crash. It was worse — it was silent. Some jobs were marked done in the database with empty content. No error thrown, no alert fired.

It took me embarrassingly long to find this, because I was looking at the OpenAI call, not the code around it. The actual bug: our backoff retry on 429 returned undefined on the 5th failed attempt instead of throwing, because of a leftover return; from an earlier version of the function that I never deleted.

// The bug, hiding in plain sight
if (err.status === 429 && attempt < MAX_ATTEMPTS) {
  // ... backoff logic
  return generateContent(prompt, attempt + 1);
}
return; // <-- this. silently swallowed every other error type
        //     and fell through after max retries.

Jobs that exhausted their retries didn't fail loudly — they just returned nothing, which got written to the content column as an empty string, which got marked done. From the dashboard, it looked like success.

Fixed by actually re-throwing instead of swallowing:

if (err.status === 429 && attempt < MAX_ATTEMPTS) {
  const baseDelay = Math.min(1000 * 2 ** attempt, 30000);
  const jitter = Math.random() * 500;
  await new Promise((r) => setTimeout(r, baseDelay + jitter));
  return generateContent(prompt, attempt + 1);
}
throw err; // exhausted retries or non-429 error — surface it, don't eat it

I'm still a little annoyed at myself for this one. It's not a scaling problem in the architecture sense — it's a stale line of code that only became visible once we had enough volume for retries to actually exhaust.

Where Redis came in

Once the pool and the queue were stable, we noticed a chunk of generation requests were near-duplicates — same keyword, same tone, same options, submitted minutes apart by the same account re-running a batch after tweaking one field.

We added Redis purely as a result cache, keyed on a hash of the prompt + options, with a short TTL:

const redis = require('redis').createClient({ url: process.env.REDIS_URL });
await redis.connect();

async function generateWithCache(prompt, options) {
  const cacheKey = `gen:${crypto
    .createHash('sha256')
    .update(prompt + JSON.stringify(options))
    .digest('hex')}`;

  const cached = await redis.get(cacheKey);
  if (cached) return cached;

  const content = await generationQueue.add(() =>
    processArticleJob({ prompt, options })
  );

  // 1 hour TTL — long enough to catch re-runs in the same editing
  // session, short enough that nobody gets stale content days later
  await redis.set(cacheKey, content, { EX: 3600 });
  return content;
}

This wasn't the architecturally interesting fix of the week. It was the cheap one. It knocked out somewhere between 10-15% of our OpenAI calls during a typical bulk batch, which mattered more for cost than for the rate limit problem — by the time Redis was in, the queue was already keeping us under the limit on its own.

What's next

The pool, the queue, and Redis got us stable at 500. I don't think they get us to 5,000 — the next bottleneck I'm watching is Postgres write contention on the jobs table itself, since every status update is a write, and a big enough batch means a lot of writes to one table at once.

I haven't decided whether that's a partitioning problem or a "stop writing intermediate status updates so often" problem. Leaning toward the second since it's simpler, but I want to see where it actually breaks before I build for a problem I don't have yet.

Open question for the comments

If you've scaled a job queue past the point where per-job DB connections work, did you go with a shared pool like this, or move status tracking out of Postgres entirely (Redis, in-memory, something else)? I went with the boring option here and I'm wondering if I'm going to regret it at the next order of magnitude.

PostAll vs Manual Content Creation: A Developer's Performance Breakdown

Aakash Gour — Mon, 15 Jun 2026 05:49:58 +0000

I spent three weeks running the same content tasks three ways — manually, with raw ChatGPT, and through PostAll — and logging every metric I could reasonably capture.

Not because I needed to convince myself. I built PostAll. I'm biased. But a few beta users kept asking me the question I'd been avoiding: "How much faster is this, actually? Give me real numbers."

So I stopped hand-waving and started measuring.

Here's what I found — including the places PostAll underperformed, the places raw ChatGPT surprised me, and the specific workflow conditions where each approach makes sense.

The Methodology (And Its Honest Limitations)

Before we get to the numbers, here's how I structured the test — and where the methodology breaks down.

What I tested:

50 blog posts (800–1,200 words each), general B2B SaaS topics
100 product descriptions (150–250 words), e-commerce category
50 social media caption sets (5 captions per brand asset)

What I measured:

Wall-clock time from "I need this content" to "this is CMS-ready"
API cost per output unit
Output quality score (more on how I scored this below)
Revision rate — how often the output needed meaningful edits before use

Where the methodology breaks down:
Quality scoring is always subjective. I used a rubric: factual accuracy, brand voice adherence, structural completeness, and SEO element inclusion (title tag, meta description, H2 structure). Each criterion scored 1–5 by two reviewers who didn't know which tool produced which piece. Even so — two reviewers, three weeks, one niche topic set. This is not a peer-reviewed study. It's a structured experiment from someone who builds this stuff.

Take the quality scores as directional, not definitive.

The Results: Time

This is where the gap is most obvious.

Blog Posts (800–1,200 words)

Approach	Avg. Time Per Post	Includes
Manual (human writer)	3.2 hours	Research, drafting, editing, formatting
Raw ChatGPT (GPT-4o)	47 minutes	Prompting, iteration, manual formatting, CMS prep
PostAll	8 minutes	Brief input → formatted, tagged, CMS-ready output

The manual number — 3.2 hours — surprised me. I expected higher. What that figure reflects is a competent generalist writer working on a topic they don't need to deeply research. For technical content or niche industries, that number goes up significantly.

The raw ChatGPT number — 47 minutes — is honest. You can get a decent draft in 10 minutes. But then you spend 20 minutes reformatting it, 10 minutes adding the metadata it didn't generate, and 7 minutes in copy-paste hell moving it into your CMS. That's the hidden cost that never shows up in "ChatGPT is free" calculations.

PostAll's 8 minutes includes all of that. You put in a brief, you get a Markdown-formatted post with title, meta description, H2 structure, and internal link placeholders, ready to paste into whatever CMS you use.

Product Descriptions (150–250 words)

Approach	Avg. Time Per Description	Batch of 100
Manual	28 minutes	~47 hours
Raw ChatGPT	11 minutes	~18 hours
PostAll	1.4 minutes	~2.3 hours

At scale, this is where it gets absurd. A 100-piece product description project is a realistic e-commerce request. Manual takes a week. Raw ChatGPT takes two solid days. PostAll takes an afternoon.

The 1.4 minutes includes the time I spent reviewing and approving each output (PostAll surfaces a confidence score — I reviewed anything under 80%). If you remove review time and trust the outputs completely, it's closer to 40 seconds per description. I wouldn't recommend that. But that's the ceiling.

Social Caption Sets (5 captions per asset)

Approach	Avg. Time Per Set	Notes
Manual	45 minutes	Tone research + platform formatting is brutal
Raw ChatGPT	18 minutes	Platform formatting still manual
PostAll	3 minutes	Platform rules baked into templates

The underrated problem with social content is platform-specific formatting rules. Twitter character counts, LinkedIn line break quirks, Instagram hashtag placement. Manual writers know these instinctively. ChatGPT doesn't unless you prompt it precisely every time. PostAll has this in the template layer — it's not magic, it's just pre-encoded rules I spent two days writing.

The Results: Cost

I want to be careful here because cost comparisons between a tool that charges for outputs and one where you supply your own API key are inherently apples-to-oranges. I'll show both.

Raw API Cost (What PostAll Actually Spends)

Using GPT-4o for all generation:

Blog post (1,000 words avg):
  - Prompt tokens: ~800
  - Completion tokens: ~1,200
  - Total: ~2,000 tokens
  - Cost at $0.005/1K tokens (output): ~$0.006 per post
  - Cost at $0.0025/1K tokens (input): ~$0.002 per post
  - Total API cost: ~$0.008 per blog post

Product description (200 words avg):
  - Total API cost: ~$0.002 per description

Social caption set (5 captions):
  - Total API cost: ~$0.003 per set

This is the raw spend. PostAll adds overhead on top of this — preprocessing, template rendering, CMS formatting — but the AI compute itself is extremely cheap.

What Freelancers Charge for the Same Work

Content Type	Freelancer Rate (US, mid-market)	PostAll API Cost	Multiplier
Blog post (1,000 words)	$150–$350	$0.008	~25,000x cheaper
Product description	$15–$40	$0.002	~10,000x cheaper
Social caption set	$25–$75	$0.003	~15,000x cheaper

I'm not saying PostAll replaces writers — I'll get to the quality section for why. But the cost delta is not a small optimization. It's a structural shift in what's economically feasible to produce.

The Results: Quality

This is the part I was most nervous about publishing.

Quality rubric scores (1–5 per criterion, averaged across 50 pieces per type):

Blog Posts

Criterion	Manual	Raw ChatGPT	PostAll
Factual accuracy	4.6	3.1	3.4
Brand voice adherence	4.3	2.4	3.9
Structural completeness	3.8	3.6	4.7
SEO elements present	2.9	2.1	4.8
Overall	3.9	2.8	4.2

A few things jump out here that I didn't expect:

PostAll scored higher than manual for structural completeness and SEO elements. This isn't because PostAll is smarter — it's because the template enforces structure. A human writer might skip a meta description when they're in a hurry. PostAll can't skip it; it's in the output schema.

Raw ChatGPT's brand voice score (2.4) is brutal. It writes in whatever voice it decides is appropriate for the topic. Without a system prompt tuned to a specific brand, you get a generic authoritative tone that sounds like no particular company. PostAll's brand voice score (3.9) comes from prompt engineering done once at the template level, not repeated every session.

Manual wins on factual accuracy (4.6 vs 3.4 for PostAll). This is real and important. A human writer who does research produces more reliable facts than an LLM that might hallucinate a statistic. For content where factual precision matters — technical documentation, medical, legal, financial — this gap matters a lot. For general B2B marketing content, it matters less but you still need a review step.

Revision Rates

This metric ended up being the most practically useful one.

Approach	% of outputs needing significant revision
Manual	12%
Raw ChatGPT	68%
PostAll	23%

"Significant revision" = more than fixing typos and minor phrasing. Restructuring, factual correction, adding missing sections.

ChatGPT's 68% revision rate is the honest number that kills the "ChatGPT is free" argument. If 68 out of 100 outputs need meaningful editing, you haven't automated content creation — you've created a first-draft generator with a bottleneck at review.

PostAll's 23% is better but not a solved problem. The pieces that needed revision were mostly ones where the brief was ambiguous or where the topic required specific knowledge we hadn't encoded in the template.

What PostAll Gets Wrong (Honest Edition)

I'd be doing you a disservice if I stopped at "PostAll scored 4.2 overall."

PostAll is bad at nuance it hasn't been trained on. The brand voice templates I built took me 2 weeks of iteration. For a new client with unusual voice requirements, that upfront cost is real. Raw ChatGPT lets you iterate voice in the prompt — PostAll makes you bake it into a template first.

PostAll hallucinates at the same rate as the underlying model. I made a mistake in early beta by implying our quality checks caught factual errors. They catch structural errors and formatting errors. They don't fact-check. If GPT-4o invents a statistic, PostAll will deliver it formatted beautifully with a confident SEO score.

PostAll's 8-minute blog post number assumes a good brief. If the brief is vague — "write about cloud security" — the output is vague. Garbage in, formatted garbage out. The time savings require a discipline investment in brief quality that some teams aren't ready to make.

The 23% revision rate hides a distribution. Topics PostAll knows well (because I've run hundreds of similar pieces) revise at ~10%. Topics at the edge of template coverage revise at ~40%. The average is 23% but the experience is bimodal.

When to Use Each Approach

The honest answer: these tools serve different jobs.

Use manual writing when:

The content will be bylined and the author's credibility is part of the value
Factual accuracy is non-negotiable (medical, legal, technical docs)
The content requires original research, interviews, or proprietary data
You're building long-form thought leadership that represents a real point of view

Use raw ChatGPT when:

You're prototyping a content strategy and don't know your voice yet
The volume is low enough that per-piece iteration is manageable
You need something that doesn't exist in any of your templates
You're a developer who's comfortable writing system prompts and iterating in-session

Use PostAll when:

You have a defined content type you produce repeatedly (product descriptions, weekly newsletters, social content)
You have a brand voice you can encode into a template once
Volume is high enough that the 8-minute vs 47-minute difference actually compounds
Your CMS integration can consume structured output directly

The Code That Makes the Timing Difference

The 8 minutes vs 47 minutes for blog posts isn't magic. It's this:

// PostAll's blog post pipeline — what actually runs
async function generateBlogPost(brief, templateId) {
  const template = await db.templates.findOne({ id: templateId });

  // Pre-built system prompt with brand voice, formatting rules, output schema
  const systemPrompt = template.systemPrompt;

  const userPrompt = `
    Topic: ${brief.topic}
    Target keyword: ${brief.primaryKeyword}
    Secondary keywords: ${brief.secondaryKeywords.join(', ')}
    Audience: ${brief.audience}
    Tone notes: ${brief.toneNotes || 'use template default'}
    Word count: ${brief.wordCount || template.defaultWordCount}

    Required output structure (JSON):
    {
      "title": "SEO title under 60 chars",
      "metaDescription": "Meta description under 155 chars",
      "slug": "url-friendly-slug",
      "body": "Full markdown body with H2/H3 structure",
      "tags": ["tag1", "tag2"],
      "internalLinkSuggestions": ["page1", "page2"]
    }
  `;

  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: userPrompt }
    ],
    // JSON mode — forces structured output, eliminates parsing failures
    response_format: { type: "json_object" },
    max_tokens: 2500,
    temperature: 0.7,
  });

  const output = JSON.parse(response.choices[0].message.content);

  // Quality gate — structure check before it ever hits the queue
  validateOutputStructure(output, template.requiredFields);

  // Confidence score — surface low-confidence outputs for human review
  output.confidenceScore = await scoreOutput(output, brief, template);

  await db.content.insert({ ...output, briefId: brief.id, templateId });

  return output;
}

What makes this faster than doing it manually in ChatGPT:

response_format: { type: "json_object" } — this is the single biggest time-saver. Without JSON mode, you get markdown prose you have to parse. With it, you get a structured object you can immediately write to your CMS. This eliminated ~15 minutes of copy-paste work per piece.
The system prompt lives in the template, not the session. You don't re-explain brand voice every time. The template does it once.
validateOutputStructure() runs before anything else. If the output is missing required fields, it retries immediately rather than letting a broken piece through to review.

The scoreOutput() function deserves its own post — it's a second LLM call that evaluates the primary output against the brief. That's the 23% revision rate reduction in practice. Not a magic quality filter — just a structured check that catches the obvious misses before a human has to.

What This Actually Means for Your Content Stack

If you're a developer building a content system for a client, or evaluating whether to build PostAll-like tooling in-house, here's the practical takeaway:

The time savings are real and they compound. A team producing 50 blog posts a month saves roughly 170 hours with this approach. At a $75/hour blended rate for whoever was doing that work, that's $12,750/month. The cost to run the AI is around $25.

But the quality tradeoff is also real. You're trading human judgment on factual accuracy and nuance for consistency and scale. The teams where this works best are the ones who are honest about which content actually needs that judgment and which doesn't.

Most content teams are applying human judgment uniformly across everything. That's the problem worth fixing — not "how do we generate content faster" but "how do we route content to the right production method based on what it actually requires."

PostAll is my attempt at one answer. The benchmark says it's a real answer. But "real" and "complete" aren't the same thing.

The full test data (anonymized) and the scoring rubric spreadsheet are available on GitHub: github.com/postall-tool/benchmark-2025. If you run a similar test with different content types or topic areas, I'd genuinely like to see the numbers — my methodology has blind spots I haven't found yet.

What part of this surprised you most? I'll be honest: the 68% ChatGPT revision rate was higher than I expected. Curious if that matches what you've seen.

Using PostAll's API to Automate Your Content Workflow: A Getting-Started Guide

Aakash Gour — Thu, 11 Jun 2026 06:17:24 +0000

I didn't set out to build a content API. I set out to stop copy-pasting.

Every week, the same ritual: open a doc, stare at a blank page, write a headline, delete it, write it again. Multiply that by every client, every product page, every email drip campaign. I wasn't doing creative work — I was doing assembly-line work while pretending it was creative.

PostAll started as a script I wrote to stop doing that. The API is what that script became after other developers asked if they could use it too.

This guide walks you through integrating PostAll's API into your own workflow — authentication, the endpoints you'll actually use, real working code in both Python and Node.js, and the specific places things will break before they work. By the end, you'll have a functioning pipeline that generates formatted, CMS-ready content programmatically.

What you'll build

A script that takes a list of content briefs (keywords, tone, target length) and returns publish-ready content — with proper formatting, metadata, and error handling for the rate limits you'll hit in production.

Here's the shape of what you're building:

[ CSV of briefs ] → [ PostAll API ] → [ formatted content objects ] → [ your CMS / database ]

The full working code for both languages is at the end of each section. I'll explain the interesting parts inline.

Prerequisites

A PostAll account with API access enabled (free tier works for this guide — rate limits noted below)
Node.js 18+ or Python 3.10+
Basic familiarity with async/await in either language
An HTTP client: axios or native fetch for Node, httpx for Python

Step 1: Authentication

PostAll uses API key authentication. Every request needs your key in the Authorization header.

Get your key: Dashboard → Settings → API Keys → Generate New Key

Store it as an environment variable. Never hardcode it.

export PostAll_API_KEY="postall_live_xxxxxxxxxxxxxxxxxxxx"

Your key has two prefixes: postall_live_ for production, postall_test_ for the sandbox. The sandbox returns real-shaped responses with placeholder content — useful for testing your pipeline without burning request quota.

Verify authentication before building anything else:

// verify-auth.js
const PostAll_API_BASE = "https://api.usepostall.io/v1";

async function verifyAuth() {
  const response = await fetch(`${PostAll_API_BASE}/account`, {
    headers: {
      Authorization: `Bearer ${process.env.PostAll_API_KEY}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    // 401 = bad key, 403 = key exists but no API access on your plan
    throw new Error(`Auth failed: ${response.status} ${response.statusText}`);
  }

  const account = await response.json();
  console.log(`Authenticated as: ${account.email}`);
  console.log(`Plan: ${account.plan} | Requests remaining: ${account.quota.remaining}`);
  return account;
}

verifyAuth().catch(console.error);

Run this first. A 403 means your account plan doesn't include API access — upgrade or contact support before debugging anything else.

Step 2: The three endpoints you'll actually use

PostAll has a full REST API, but 90% of automation use cases come down to three endpoints:

Endpoint	Method	What it does
`/v1/generate`	POST	Generate a single content piece
`/v1/batch`	POST	Queue multiple generations (async)
`/v1/batch/:id`	GET	Poll a batch job for results

There's also /v1/templates (GET) to list your saved prompt templates, and /v1/content/:id (GET/PATCH/DELETE) for managing existing content — but start with generate and batch.

Step 3: Your first generation

Let's generate one piece of content end-to-end before building the pipeline.

The request shape:

// generate-single.js
const PostAll_API_BASE = "https://api.usepostall.io/v1";

async function generateContent(brief) {
  const response = await fetch(`${PostAll_API_BASE}/generate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PostAll_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: brief.type,           // "blog_post" | "product_description" | "email" | "social"
      topic: brief.topic,
      tone: brief.tone,           // "professional" | "conversational" | "technical" | "playful"
      target_length: brief.target_length, // word count target, not a hard limit
      format: "markdown",         // "markdown" | "html" | "plain"
      metadata: {
        seo_optimize: true,       // adds meta_description and focus_keyword to response
        include_headings: true,
      },
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Generation failed: ${error.message}`);
  }

  return response.json();
}

// Test it
generateContent({
  type: "blog_post",
  topic: "how to reduce JavaScript bundle size in 2025",
  tone: "technical",
  target_length: 800,
}).then((result) => {
  console.log("Title:", result.content.title);
  console.log("Word count:", result.content.word_count);
  console.log("Meta description:", result.metadata.meta_description);
  // result.content.body contains the full markdown
});

The response shape:

{
  "id": "gen_01hx4k2m9f...",
  "status": "complete",
  "content": {
    "title": "7 Ways to Reduce Your JavaScript Bundle Size in 2025",
    "body": "## The bundle problem\n\nYour users...",
    "word_count": 847,
    "reading_time_minutes": 4
  },
  "metadata": {
    "meta_description": "Learn the most effective strategies for reducing JavaScript bundle size...",
    "focus_keyword": "reduce JavaScript bundle size",
    "tokens_used": 1203
  },
  "created_at": "2025-01-15T14:32:11Z"
}

The id field matters — you'll use it to retrieve or update content later. Store it.

Step 4: Batch generation for real volume

Single generation works for interactive use. For processing a list of briefs, use the batch endpoint. It's async: you submit the job, get a batch_id back, then poll for results.

Why async matters here: batch jobs can take 30 seconds to several minutes depending on size. Don't try to do this synchronously with a timeout — you'll time out on large batches and have no idea what succeeded.

// batch-pipeline.js
const PostAll_API_BASE = "https://api.usepostall.io/v1";

// Step 1: Submit the batch
async function submitBatch(briefs) {
  const response = await fetch(`${PostAll_API_BASE}/batch`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PostAll_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      items: briefs.map((brief) => ({
        type: brief.type,
        topic: brief.topic,
        tone: brief.tone || "professional",
        target_length: brief.target_length || 500,
        format: "markdown",
        // Optional: tag each item for easier result mapping
        external_id: brief.id,
      })),
      // Webhook URL to hit when complete — highly recommended over polling
      webhook_url: process.env.PostAll_WEBHOOK_URL || null,
    }),
  });

  const batch = await response.json();
  return batch.id; // e.g. "batch_01hx4k2m9f..."
}

// Step 2: Poll until done
async function pollBatch(batchId, intervalMs = 3000) {
  const headers = {
    Authorization: `Bearer ${process.env.PostAll_API_KEY}`,
    "Content-Type": "application/json",
  };

  while (true) {
    const response = await fetch(`${PostAll_API_BASE}/batch/${batchId}`, { headers });
    const batch = await response.json();

    console.log(`Status: ${batch.status} | Progress: ${batch.completed}/${batch.total}`);

    if (batch.status === "complete") {
      return batch.results;
    }

    if (batch.status === "failed") {
      throw new Error(`Batch failed: ${batch.error}`);
    }

    // "processing" or "queued" — wait and try again
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
}

// Put it together
async function runBatchPipeline(briefs) {
  console.log(`Submitting batch of ${briefs.length} items...`);
  const batchId = await submitBatch(briefs);
  console.log(`Batch ID: ${batchId} — polling for results...`);

  const results = await pollBatch(batchId);
  console.log(`Done. ${results.length} items generated.`);
  return results;
}

Step 5: The same pipeline in Python

For those of you running data pipelines, automations, or integrations in Python:

# PostAll_pipeline.py
import os
import time
import httpx
from typing import Optional

PostAll_API_BASE = "https://api.usepostall.io/v1"

def get_headers():
    api_key = os.environ.get("PostAll_API_KEY")
    if not api_key:
        raise EnvironmentError("PostAll_API_KEY not set")
    return {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }

def generate_single(brief: dict) -> dict:
    """Generate one content piece synchronously."""
    with httpx.Client(timeout=30.0) as client:
        response = client.post(
            f"{PostAll_API_BASE}/generate",
            headers=get_headers(),
            json={
                "type": brief["type"],
                "topic": brief["topic"],
                "tone": brief.get("tone", "professional"),
                "target_length": brief.get("target_length", 500),
                "format": "markdown",
                "metadata": {"seo_optimize": True},
            },
        )
        response.raise_for_status()
        return response.json()

def submit_batch(briefs: list[dict]) -> str:
    """Submit a batch job and return the batch ID."""
    with httpx.Client(timeout=30.0) as client:
        response = client.post(
            f"{PostAll_API_BASE}/batch",
            headers=get_headers(),
            json={
                "items": [
                    {
                        "type": b["type"],
                        "topic": b["topic"],
                        "tone": b.get("tone", "professional"),
                        "target_length": b.get("target_length", 500),
                        "format": "markdown",
                        "external_id": b.get("id"),
                    }
                    for b in briefs
                ]
            },
        )
        response.raise_for_status()
        return response.json()["id"]

def poll_batch(batch_id: str, interval_seconds: float = 3.0) -> list[dict]:
    """Poll a batch job until complete. Returns list of results."""
    with httpx.Client(timeout=30.0) as client:
        while True:
            response = client.get(
                f"{PostAll_API_BASE}/batch/{batch_id}",
                headers=get_headers(),
            )
            response.raise_for_status()
            batch = response.json()

            print(f"Status: {batch['status']} | Progress: {batch['completed']}/{batch['total']}")

            if batch["status"] == "complete":
                return batch["results"]

            if batch["status"] == "failed":
                raise RuntimeError(f"Batch failed: {batch.get('error')}")

            time.sleep(interval_seconds)


# Example: run from a list of dicts
if __name__ == "__main__":
    briefs = [
        {"id": "1", "type": "product_description", "topic": "noise-cancelling headphones", "tone": "conversational"},
        {"id": "2", "type": "product_description", "topic": "mechanical keyboard", "tone": "technical"},
        {"id": "3", "type": "email", "topic": "product launch announcement", "target_length": 200},
    ]

    batch_id = submit_batch(briefs)
    print(f"Submitted batch: {batch_id}")
    results = poll_batch(batch_id)

    for item in results:
        print(f"\n--- {item['external_id']} ---")
        print(f"Title: {item['content']['title']}")
        print(f"Words: {item['content']['word_count']}")

What can go wrong (and will)

Rate limits

Free tier: 10 requests/minute, 100 requests/day. Pro tier: 60 requests/minute, no daily cap.

The API returns 429 Too Many Requests when you hit the limit, with a Retry-After header telling you how many seconds to wait. Don't ignore that header. I learned this the hard way — a tight retry loop without backoff will keep 429-ing you indefinitely.

// Respect the Retry-After header
async function generateWithRetry(brief, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(`${POSTALL_API_BASE}/generate`, {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.POSTALL_API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify(brief),
    });

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "5", 10);
      console.log(`Rate limited. Waiting ${retryAfter}s...`);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }
  throw new Error("Max retries exceeded");
}

Batch jobs don't fail loudly

If one item in a batch fails, the rest still complete. The failed item shows up in results with "status": "failed" and an error field. Check each item's status — don't assume the whole batch succeeded just because batch.status === "complete".

results.forEach((item) => {
  if (item.status === "failed") {
    console.error(`Item ${item.external_id} failed:`, item.error);
    // Log it, re-queue it, or flag for manual review
  }
});

Webhooks are more reliable than polling

If you're running batches in a server environment, set webhook_url when submitting and handle the POST PostAll sends when the job is done. Polling works for scripts, but it's wasteful and fails silently if your process exits. The webhook payload is the same shape as the poll response — swap the logic, not the data handling.

Content length is a target, not a guarantee

target_length: 800 gets you a content piece in the 700–950 word range in my testing. If you need strict character counts for database constraints, validate and truncate after the fact — don't rely on the API hitting an exact number.

A note on the test vs production key

Run your integration against postall_test_ keys until you're confident the pipeline handles errors correctly. Test mode returns structurally valid responses with placeholder content — great for schema validation and error path testing without burning API quota.

Switch to postall_live_ when:

Your retry logic handles 429s correctly
You're checking per-item status in batch results
You're storing the id field from responses (you'll want it for content management later)

Where to go from here

This covers the generation layer. The next pieces you'll likely want to build:

Template management — /v1/templates lets you save and version your prompt configurations, so you're not repeating the full brief object every request.
Content CRUD — Once you're generating programmatically, you'll want to retrieve, update, and delete via /v1/content/:id. Especially useful if you're feeding Postall output into a CMS with a review step.
Webhook handling — If you're building a production automation rather than a script, set up a webhook receiver and drop the polling loop entirely.

The full working code from this guide is on GitHub: github.com/usepostall/api-quickstart. Both the Node and Python examples are there with a sample CSV loader and a basic webhook receiver.

What are you automating first? Drop it in the comments — I'm particularly curious what use cases people hit that the /generate endpoint doesn't cover out of the box.

Already using the PostAll API? I'd love to know what your retry/backoff strategy looks like at scale — the Retry-After approach above works at low volume but I'm still iterating on the right pattern for 1000+ item batches.

How PostAll's Content Pipeline Actually Works: A Full Architecture Breakdown

Aakash Gour — Mon, 08 Jun 2026 05:59:37 +0000

I'm going to show you the entire internal architecture of PostAll — the content automation platform I've been building — because I think there's a gap in how people talk about AI content tools publicly.

Most founders describe their product in terms of outcomes: "generate 10x content faster," "consistent brand voice," "scales with your team." That's fine for a landing page. But if you're a developer evaluating whether to build something similar, or trying to understand what makes an AI content pipeline actually work at scale, outcome-speak tells you nothing.

So here's what I should have read when I started: how a production content automation system is actually structured, what each layer does, where things break, and the decisions I made — and regret — along the way.

This is not a tutorial. It's a transparency post. PostAll is live. This is how it works.

The 30-second version

PostAll has five distinct layers:

Queue system — ingests jobs, prioritizes them, handles retries
Orchestration layer — breaks content requests into atomic tasks
LLM layer — calls the models, handles rate limits and fallbacks
Formatting engine — transforms raw LLM output into structured content
CMS connectors — pushes formatted content to wherever the client wants it

Each layer is independently deployable and has its own failure modes. The worst mistake I made early on was treating them as one monolith, and I'll explain exactly what broke.

The queue system

What it does

Every content request — whether it's one blog post or 500 product descriptions — enters PostAll as a job. Jobs hit the queue before anything else happens. The queue is the single source of truth for what work exists, what's in progress, and what's failed.

I use BullMQ (backed by Redis) for this. I evaluated Postgres-backed queues (pg-boss, Graphile Worker) first. They're fine for lower throughput. At scale, the Redis-backed approach handles bursts better and the job visibility tools in BullMQ's UI saved me significant debugging time in production.

// job-producer.ts
import { Queue } from 'bullmq';
import { redis } from './redis-client';

const contentQueue = new Queue('content-generation', {
  connection: redis,
  defaultJobOptions: {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 2000, // 2s, 4s, 8s — stays inside most LLM retry windows
    },
    removeOnComplete: { count: 500 }, // keep last 500 completed jobs for audit
    removeOnFail: false,              // keep all failed jobs — you'll want to inspect them
  },
});

export async function enqueueContentJob(payload: ContentJobPayload) {
  const job = await contentQueue.add(
    'generate',
    payload,
    {
      priority: payload.bulkBatch ? 2 : 1, // single requests get higher priority
      jobId: `${payload.clientId}:${payload.contentId}`, // idempotent — safe to re-enqueue
    }
  );
  return job.id;
}

The jobId pattern matters. Setting it to a deterministic string means if a client double-submits (network retry, user clicking twice), BullMQ silently deduplicates. You want this. Without it, you'll spend a Friday afternoon tracking down why the same article got generated three times.

What I got wrong: worker concurrency

My initial worker config:

// WRONG — don't do this
const worker = new Worker('content-generation', processJob, {
  connection: redis,
  concurrency: 50, // I thought "more = faster"
});

At 50 concurrent workers hitting OpenAI simultaneously, I was saturating my rate limit constantly. The retries from failed requests caused a feedback loop: more retries → more failures → more retries.

The fix:

// RIGHT — sized to your actual API tier
const worker = new Worker('content-generation', processJob, {
  connection: redis,
  concurrency: 8, // OpenAI Tier 3 gives us ~3,500 RPM across all workers
  limiter: {
    max: 8,
    duration: 1000, // max 8 jobs started per second across all worker instances
  },
});

The limiter option in BullMQ is underused. It's not just about your worker — it's a global rate governor across however many worker instances you're running. With autoscaling, you can have 10 pods all pulling from the same queue. Without the limiter, 10 pods × 50 concurrency = 500 simultaneous LLM calls. That's how you get a $3,000 bill and a support ticket in the same hour.

The orchestration layer

What it does

A "content job" sounds atomic. It isn't. A single blog post request in PostAll decomposes into:

Keyword research task (if enabled)
Outline generation task
Section drafts (one per section, parallelizable)
Introduction/conclusion stitching task
SEO metadata generation task
Quality score evaluation task

The orchestration layer handles this decomposition, tracks task dependencies, and aggregates results into a coherent output.

I built this with a simple DAG (directed acyclic graph) structure rather than reaching for a workflow engine like Temporal or Inngest. For PostAll's use case, a purpose-built DAG was simpler and cheaper to operate. If I were doing multi-tenant workflows with human-in-the-loop steps, I'd reconsider.

// content-dag.ts
type TaskNode = {
  id: string;
  type: 'outline' | 'section' | 'metadata' | 'quality';
  dependsOn: string[];
  input: (context: JobContext) => Promise<TaskInput>;
  execute: (input: TaskInput) => Promise<TaskOutput>;
};

export function buildContentDAG(request: ContentRequest): TaskNode[] {
  const outline: TaskNode = {
    id: 'outline',
    type: 'outline',
    dependsOn: [],
    input: async (ctx) => ({ keyword: request.keyword, tone: request.tone }),
    execute: generateOutline,
  };

  const sections: TaskNode[] = request.sections.map((section, i) => ({
    id: `section-${i}`,
    type: 'section',
    dependsOn: ['outline'],
    input: async (ctx) => ({
      outline: ctx.results['outline'],
      sectionIndex: i,
      sectionTitle: section.title,
    }),
    execute: generateSection,
  }));

  const metadata: TaskNode = {
    id: 'metadata',
    type: 'metadata',
    dependsOn: sections.map((s) => s.id), // needs all sections complete
    input: async (ctx) => ({ fullContent: assembleContent(ctx) }),
    execute: generateMetadata,
  };

  return [outline, ...sections, metadata];
}

The executor resolves the DAG topologically, runs independent nodes in parallel, and passes results through context:

// dag-executor.ts
async function executeDag(nodes: TaskNode[], jobId: string): Promise<JobContext> {
  const context: JobContext = { jobId, results: {}, errors: {} };
  const remaining = [...nodes];

  while (remaining.length > 0) {
    // find nodes whose dependencies are all complete
    const ready = remaining.filter((node) =>
      node.dependsOn.every((dep) => dep in context.results)
    );

    if (ready.length === 0) {
      throw new Error(`DAG deadlock in job ${jobId} — circular dependency or failed prerequisite`);
    }

    // run ready nodes in parallel
    await Promise.allSettled(
      ready.map(async (node) => {
        try {
          const input = await node.input(context);
          context.results[node.id] = await node.execute(input);
        } catch (err) {
          context.errors[node.id] = err;
          // don't throw — let other branches complete, fail job at end
        }
      })
    );

    // remove completed nodes
    ready.forEach((node) => {
      const idx = remaining.indexOf(node);
      remaining.splice(idx, 1);
    });
  }

  return context;
}

The Promise.allSettled choice is intentional. If one section fails, you still want the other sections to complete. You can fail the job at the end with partial results, which is far better than losing all work because one 500-word section errored.

The LLM layer

What it does

Every LLM call in PostAll goes through a single abstraction: the LLMClient. This class handles model selection, prompt construction, retry logic, fallback routing, and cost tracking. Nothing in the codebase calls OpenAI directly.

// llm-client.ts
export class LLMClient {
  private providers: ProviderConfig[];

  constructor(config: LLMClientConfig) {
    this.providers = config.providers; // ordered by preference
  }

  async complete(request: CompletionRequest): Promise<CompletionResponse> {
    for (const provider of this.providers) {
      try {
        const result = await this.callProvider(provider, request);
        await this.trackUsage(provider.name, result.usage);
        return result;
      } catch (err) {
        if (this.isRateLimit(err) || this.isServerError(err)) {
          // try next provider
          continue;
        }
        throw err; // bad request, auth error — don't retry with another provider
      }
    }
    throw new Error('All providers exhausted');
  }

  private async callProvider(
    provider: ProviderConfig,
    request: CompletionRequest
  ): Promise<CompletionResponse> {
    const client = this.getClient(provider.name);
    const response = await client.chat.completions.create({
      model: provider.model,
      messages: this.buildMessages(request),
      max_tokens: request.maxTokens ?? 2000,
      temperature: request.temperature ?? 0.7,
      response_format: request.structured ? { type: 'json_object' } : undefined,
    });

    return {
      content: response.choices[0].message.content ?? '',
      usage: {
        promptTokens: response.usage?.prompt_tokens ?? 0,
        completionTokens: response.usage?.completion_tokens ?? 0,
        provider: provider.name,
        model: provider.model,
      },
    };
  }

  private isRateLimit(err: unknown): boolean {
    return err instanceof Error && err.message.includes('429');
  }

  private isServerError(err: unknown): boolean {
    return err instanceof Error && err.message.includes('5');
  }
}

The fallback routing config

// llm-config.ts
export const llmConfig: LLMClientConfig = {
  providers: [
    {
      name: 'openai',
      model: 'gpt-4o',
      apiKey: process.env.OPENAI_API_KEY!,
    },
    {
      name: 'anthropic',
      model: 'claude-sonnet-4-20250514', // fallback for rate limit hits
      apiKey: process.env.ANTHROPIC_API_KEY!,
    },
  ],
};

Multi-provider fallback sounds complicated. It's mostly just the ordering. The insight that took me too long to reach: don't try to be smart about routing at call time. Keep a priority list, try them in order, move on if one fails. Smart routing (latency-based, cost-based) added complexity with no meaningful real-world gain at my current scale.

Token budgeting

One thing that bit me early: LLM requests for long-form content can exceed context limits in ways that are hard to predict at job creation time. PostAll now estimates token usage before each call:

function estimatePromptTokens(messages: Message[]): number {
  // rough estimate: 1 token ≈ 4 characters for English prose
  const charCount = messages.reduce((sum, m) => sum + m.content.length, 0);
  return Math.ceil(charCount / 4) + 100; // +100 overhead for formatting
}

async function callWithBudget(
  client: LLMClient,
  request: CompletionRequest
): Promise<CompletionResponse> {
  const MODEL_CONTEXT_LIMIT = 128_000; // gpt-4o context window
  const estimatedPrompt = estimatePromptTokens(request.messages);
  const safeMaxTokens = Math.min(
    request.maxTokens ?? 2000,
    MODEL_CONTEXT_LIMIT - estimatedPrompt - 500 // leave buffer
  );

  if (safeMaxTokens < 200) {
    throw new Error('Prompt too long for requested output length — consider chunking');
  }

  return client.complete({ ...request, maxTokens: safeMaxTokens });
}

This saves you from silent truncation — which is the failure mode where the model just... stops mid-sentence because you ran out of context window and you have no idea why.

The formatting engine

What it does

Raw LLM output is text. What clients actually need is structured, formatted content ready to paste into a CMS — proper heading hierarchy, internal links in the right format, meta descriptions within character limits, image alt text suggestions, and so on.

The formatting engine handles this transformation. It runs after every LLM call that produces content (not metadata calls).

// formatter.ts
export type FormatTarget = 'markdown' | 'html' | 'wordpress' | 'contentful-richtext';

export async function formatContent(
  rawContent: string,
  target: FormatTarget,
  options: FormatOptions
): Promise<FormattedContent> {
  // 1. Parse raw text into a content tree
  const tree = parseContentTree(rawContent);

  // 2. Apply structural fixes
  const normalized = normalizeHeadings(tree);         // enforce H2 → H3 hierarchy
  const withKeyword = injectKeywordDensity(normalized, options.keyword, 0.012); // ~1.2%
  const withLinks = applyInternalLinks(withKeyword, options.internalLinkMap);

  // 3. Validate SEO constraints
  validateSeoConstraints(withLinks, {
    minWords: options.minWords ?? 800,
    maxMetaDescLength: 160,
    titleTagRange: [50, 60],
  });

  // 4. Serialize to target format
  return serialize(withLinks, target);
}

The most underrated function in this whole stack is normalizeHeadings. LLMs are inconsistent about heading levels. You'll get H1s inside H3 sections, H4s appearing before H2s, and occasionally no structure at all. A single regex pass doesn't fix it — you need to understand the tree.

function normalizeHeadings(tree: ContentTree): ContentTree {
  let expectedLevel = 2; // PostAll-generated content starts at H2 (H1 is the page title)

  return walkTree(tree, (node) => {
    if (node.type !== 'heading') return node;

    if (node.level < expectedLevel) {
      // heading skipped levels — promote to expected
      return { ...node, level: expectedLevel };
    }

    if (node.level > expectedLevel + 1) {
      // heading jumped down too far — demote to one level below expected
      return { ...node, level: expectedLevel + 1 };
    }

    expectedLevel = node.level;
    return node;
  });
}

What I wish I'd built earlier: a validation layer with human-readable errors

For six months, validation failures surfaced as generic job errors. I'd get a failed job, dig through logs, and eventually find something like ValidationError: heading_hierarchy_violated. Not helpful.

Now every validation failure returns a structured report:

type ValidationReport = {
  passed: boolean;
  issues: Array<{
    severity: 'error' | 'warning';
    code: string;
    message: string;       // human-readable
    location?: string;     // e.g. "Section 2, paragraph 3"
    suggestion?: string;   // what to do about it
  }>;
};

This also feeds back into the LLM layer for automatic retry with targeted instructions: if the meta description is too long, the retry prompt includes "The previous meta description was 184 characters. Rewrite it to be under 160 characters." This reduced formatting-related job failures by 67% over two weeks.

The CMS connectors

What it does

Formatted content needs to go somewhere. PostAll currently supports WordPress (REST API), Contentful, Webflow CMS, and a generic webhook target. Each connector is a thin adapter that translates PostAll's internal FormattedContent type to whatever the target CMS expects.

// connectors/wordpress.ts
export class WordPressConnector implements CMSConnector {
  async publish(content: FormattedContent, config: WordPressConfig): Promise<PublishResult> {
    const payload = {
      title: content.metadata.title,
      content: content.body.html,    // WP expects HTML
      status: config.publishImmediately ? 'publish' : 'draft',
      slug: slugify(content.metadata.title),
      meta: {
        _yoast_wpseo_metadesc: content.metadata.metaDescription,
        _yoast_wpseo_title: content.metadata.seoTitle,
        _yoast_wpseo_focuskw: content.metadata.keyword,
      },
      categories: config.categoryIds ?? [],
      tags: config.tagIds ?? [],
    };

    const response = await fetch(`${config.siteUrl}/wp-json/wp/v2/posts`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Basic ${Buffer.from(`${config.username}:${config.appPassword}`).toString('base64')}`,
      },
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new CMSConnectorError('wordpress', response.status, error.message);
    }

    const post = await response.json();
    return { contentId: post.id.toString(), url: post.link, status: 'published' };
  }
}

Each connector handles its own error mapping. A 409 from Contentful (slug conflict) is a different recovery path than a 401 (expired auth token). The CMSConnectorError type carries enough context for the job system to decide whether to retry, notify the client, or surface a specific error message.

The webhook target

The most useful connector I built turned out to be the simplest: a generic webhook. When a client doesn't use any of the supported CMS platforms, they give PostAll a URL and we POST formatted content as JSON to it. They handle their own delivery.

// connectors/webhook.ts
export class WebhookConnector implements CMSConnector {
  async publish(content: FormattedContent, config: WebhookConfig): Promise<PublishResult> {
    const payload = {
      version: '1.0',
      timestamp: new Date().toISOString(),
      jobId: content.jobId,
      content: {
        title: content.metadata.title,
        body: {
          markdown: content.body.markdown,
          html: content.body.html,
        },
        metadata: content.metadata,
        seoData: content.seoData,
      },
    };

    // sign the payload so clients can verify it came from PostAll
    const signature = createHmac('sha256', config.signingSecret)
      .update(JSON.stringify(payload))
      .digest('hex');

    const response = await fetch(config.url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-PostAll-Signature': `sha256=${signature}`,
        'X-PostAll-Event': 'content.published',
      },
      body: JSON.stringify(payload),
    });

    // treat 2xx as success, anything else as failure
    if (!response.ok) {
      throw new CMSConnectorError('webhook', response.status, `Webhook returned ${response.status}`);
    }

    return { contentId: content.jobId, url: config.url, status: 'delivered' };
  }
}

HMAC signing is something I added after the first time a client asked "how do we know this request is actually from you?" Now every webhook delivery is signed with a per-client secret. The verification code on their end is four lines of Python or Node. Worth adding from day one.

The architecture in one diagram

Here's how these five layers connect at runtime for a single content job:

Client Request
      │
      ▼
┌─────────────┐
│  Queue      │  BullMQ / Redis — ingests, prioritizes, handles retries
│  System     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Orchestration│  DAG executor — decomposes job into parallel tasks
│   Layer     │
└──────┬──────┘
       │  (multiple parallel tasks)
       ▼
┌─────────────┐
│   LLM       │  Multi-provider client — OpenAI primary, Anthropic fallback
│   Layer     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Formatting │  Heading normalization, SEO validation, keyword density
│   Engine    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    CMS      │  WordPress / Contentful / Webflow / Webhook
│ Connectors  │
└─────────────┘

Each box is a separate module with its own error handling and retry budget. The queue system is the only layer that knows about job persistence — everything below it is stateless.

What I'd do differently

1. I would have built the formatting engine first.

The LLM layer gets all the attention because models are interesting. But the formatting engine is where most client complaints come from. Heading was wrong, meta description was too long, link format didn't match their CMS. Investing in formatting validation early would have saved two months of reactive fixes.

2. I would have instrumented the DAG execution from day one.

Right now I can tell you how long individual LLM calls take. For the first six months, I couldn't tell you how long a job took end-to-end, or which tasks inside the DAG were the bottleneck. Turns out: metadata generation was consistently the slowest step, not section drafting. I only discovered this when I added distributed tracing. It was a 15-minute fix once I knew where to look.

3. The multi-provider fallback is table stakes, not a "nice-to-have."

I treated provider fallback as a future optimization. During an OpenAI incident in early production, I had 40 jobs stuck with no fallback, clients emailing me, and nothing to do but wait. Anthropic as a fallback target took me a few hours to wire in. It should have been there before the first paying customer.

Where PostAll is now

The current pipeline processes around 800 content jobs per day with a p95 job latency of 94 seconds (from queue entry to CMS delivery). The LLM layer accounts for about 78% of that time. The formatting engine accounts for about 14%. The queue system and CMS connectors split the rest.

Error rate over the last 30 days: 1.3% of jobs require manual intervention. About 40% of those are auth issues on the client's CMS (expired credentials, changed endpoints). The other 60% are LLM-layer failures that exhaust retries — usually structured output that doesn't parse correctly on the first three attempts.

There's a lot still to build. Quality scoring is currently rule-based (reading level, keyword density, heading count). The next version will use a lightweight model eval layer to assess coherence and factual consistency. That's a different post.

If you're building something similar — a content pipeline, a document generation system, anything that orchestrates LLM calls at scale — I'm curious what your DAG execution looks like. Did you use a workflow engine, or roll your own? The tradeoffs there are non-obvious and I'd genuinely like to hear what others landed on.

The complete source for PostAll's connector layer is on GitHub at github.com/postall-platform/connectors. The LLM client abstraction is published as a standalone npm package: @postall-platform/llm-client. Drop a star if any of this was useful — it's the best signal I have for what to write about next.

PostAll Build Log #2: What My First Beta Users Actually Told Me (And What I Had to Rewrite)

Aakash Gour — Thu, 04 Jun 2026 06:07:41 +0000

I sent PostAll to 11 beta users three weeks ago.

I expected feedback about the UI. Maybe some complaints about output quality. A few "would be nice if..." suggestions I could politely defer.

What I got instead: three separate users hitting the same architectural assumption I'd never tested, a feature I was proud of that nobody used, and one piece of feedback that made me rewrite the job queue from scratch.

Here's what actually happened.

The Feedback I Expected vs. What I Got

My mental model of beta feedback: people would try the core flow, generate some content, and tell me what felt awkward.

The reality: two users never got past onboarding. Not because the onboarding was broken — it wasn't. Because their use case didn't map to how I'd structured the product at all.

I'd built PostAll around a "campaign" metaphor: you define a topic, set parameters, generate a batch of articles. Clean. Logical. Made total sense to me.

User #4 (a content agency owner) opened PostAll and spent 10 minutes looking for a way to paste in a list of 60 keywords and just... run them. No campaign setup. No parameter tuning. Just: here are the keywords, go.

User #7 (an e-commerce founder) wanted to generate product descriptions one at a time, from inside a workflow that already existed in another tool. He wasn't looking for a campaign — he was looking for an API endpoint with sensible defaults.

Same product. Completely different mental models. Both of them valid.

The campaign abstraction I'd designed was the right structure for me, building the thing. It was the wrong structure for people who just needed output fast.

The Architecture Change I Didn't Want to Make

Here's what the original job flow looked like:

// Original: campaigns own everything
async function enqueueCampaign(campaignId) {
  const campaign = await db.campaigns.findById(campaignId);
  const jobs = campaign.keywords.map(keyword => ({
    campaignId,
    keyword,
    parameters: campaign.parameters,
    status: 'pending'
  }));

  await db.jobs.insertMany(jobs);
  await queue.add('processCampaign', { campaignId });
}

Every job was a child of a campaign. Made sense for tracking, for billing, for grouping output. But it meant you had to create a campaign before you could generate anything.

After beta feedback, I needed jobs to be first-class:

// Revised: jobs are independent, campaigns are optional grouping
async function enqueueJob(input) {
  const { keyword, parameters, campaignId = null, userId } = input;

  const job = await db.jobs.create({
    userId,
    campaignId,      // nullable — job works without a campaign
    keyword,
    parameters: {
      ...getDefaultParameters(userId),  // sensible defaults per user
      ...parameters                      // override only what was passed
    },
    status: 'pending',
    createdAt: new Date()
  });

  await queue.add('processJob', { jobId: job.id }, {
    attempts: 3,
    backoff: { type: 'exponential', delay: 2000 }
  });

  return job;
}

This change sounds small. It took two days to implement correctly, because campaign-level analytics were baked into four different places in the codebase that assumed campaignId was always present.

The lesson: the abstraction you build first is usually built for the creator, not the user. The creator needs structure to stay sane. The user needs to get to output as fast as possible.

The Feature Nobody Used

I spent probably 12 hours building a "Content Style Guide" editor — a UI where you could define your brand voice, set tone parameters, add example sentences PostAll should emulate.

In 11 beta users across three weeks: zero used it.

I asked User #2 about it directly. She said: "Oh, I didn't know what that was for. I just typed what I wanted in the prompt box."

The fancier the UI, the higher the cognitive load to understand it. A free-text prompt field has a learning curve of zero. A multi-field style guide editor requires you to understand what "formality score" means, why you'd set it to 7 vs. 8, and whether it'll actually affect output.

I haven't deleted the style guide feature. But I've moved it three levels deeper in the settings, and I added a "Quick Generate" path that bypasses it entirely.

The One Piece of Feedback That Stung

User #9 — a freelance writer who was testing PostAll to see if it would help with client volume — sent me a Loom video. I was expecting a bug report.

Instead: she showed herself generating five articles, then pulling them all into a Google Doc to manually reformat them. Title casing, removing extra line breaks, standardizing the H2 structure. It took her longer than just editing the content.

The output quality was fine. The output format was inconsistent in ways that made it unusable without cleanup.

I'd tested PostAll's output against my own mental model of "good formatting." I hadn't tested it against what someone actually does with the output after it's generated.

The fix wasn't in the prompt. It was in the post-processing layer:

function normalizeArticleOutput(rawContent) {
  return rawContent
    // Consistent H2 formatting (model sometimes outputs ### instead of ##)
    .replace(/^#{3,}\s/gm, '## ')
    // Remove double blank lines
    .replace(/\n{3,}/g, '\n\n')
    // Title case for H2 headers (model is inconsistent)
    .replace(/^## (.+)$/gm, (_, title) => `## ${toTitleCase(title)}`)
    // Strip trailing whitespace per line
    .split('\n').map(line => line.trimEnd()).join('\n')
    .trim();
}

Simple. Should have been in v1. Wasn't, because I never watched someone actually use the output in their workflow.

What I Underestimated

Onboarding time. I thought 10 minutes to first generation was fine. Two users spent more than 20 minutes before generating anything, and both of them never came back.

The first generation is the only one that matters for retention. If someone generates garbage on the first try — wrong format, wrong length, doesn't match their mental model of "good content" — the product is dead to them regardless of how good it gets later.

I'm now adding a guided first-run flow that forces a single successful generation before anything else. Not optional. Mandatory.

Where PostAll Is Now

Job queue redesigned: campaigns are optional, not required
Quick Generate path ships next week
Output normalization layer is live
Style guide editor: still exists, now hidden by default
Onboarding: being rebuilt

The metrics that matter right now: 4 of 11 beta users have generated content more than once. I want that at 7 of 11 before I expand the beta further.

What surprised you most the first-time real users touched something you built? I keep expecting UI feedback and keep getting architecture feedback. Starting to think that's just how it goes.

Building a Multi-Platform Content Publisher: One API, Five Destinations

Aakash Gour — Mon, 01 Jun 2026 06:30:22 +0000

Every time I shipped a new article for PostAll's early beta users, I watched them paste the same content into five different dashboards. WordPress. Ghost. Webflow. Medium. Dev.to.

Copy. Paste. Adjust formatting. Fight with the rich text editor. Repeat.

I timed it once: 23 minutes per article to publish to all five platforms. If you're doing content at any kind of scale — even 10 articles a week — that's nearly 4 hours of soul-crushing manual work. Work that a computer should obviously be doing.

So I built a single publish API that handles all five simultaneously. This is the exact implementation behind PostAll's multi-platform publishing feature. I'll show you the full working code, the two approaches I tried before this one, and the specific failure modes you'll hit if you skip the parts I almost skipped.

What You'll Build

By the end of this, you'll have a Node.js service with a single POST /publish endpoint that:

Accepts a content payload (title, body, tags, metadata)
Transforms the content into each platform's required format
Publishes to all five destinations in parallel
Returns a structured result object with success/failure per platform
Handles partial failures without killing the whole batch

Here's what a successful response looks like:

{
  "status": "partial_success",
  "results": {
    "wordpress": { "success": true, "url": "https://yourblog.com/?p=1842" },
    "ghost": { "success": true, "url": "https://yourblog.ghost.io/p/your-post" },
    "webflow": { "success": true, "itemId": "64a3f1b2c3d4e5f6a7b8c9d0" },
    "medium": { "success": true, "url": "https://medium.com/@you/your-post-abc123" },
    "devto": { "success": false, "error": "Rate limit exceeded. Retry after 60s." }
  }
}

That partial failure on Dev.to? I'll show you exactly how to handle it without having to re-publish everything else.

Why This Is Harder Than It Looks

Five platforms, five completely different APIs.

WordPress uses XML-RPC or a REST API (depending on version and config). Ghost has a beautiful Admin API but requires JWT authentication with a 5-minute expiry. Webflow's CMS API is REST but requires knowing your Collection ID before you can do anything. Medium requires OAuth for full access but supports integration tokens for simpler publishing. Dev.to uses API keys but has aggressive rate limiting on free accounts.

Every platform has a different concept of "content." WordPress thinks in post_content. Ghost thinks in Mobiledoc or Lexical JSON. Webflow thinks in CMS field schemas you define yourself. Medium thinks in HTML with a title field. Dev.to thinks in Markdown with frontmatter.

The naive approach — just writing five separate functions — works until you need to change something. Then you're changing it five times. The right approach is a transform layer that sits between your canonical content format and each platform's expected format.

Prerequisites

Node.js 18+ (uses native fetch and Promise.allSettled)
Active accounts on whichever platforms you're targeting
API credentials for each (I'll list exactly what you need per platform)
Basic understanding of async/await and REST APIs

You don't need to target all five platforms immediately. The architecture is additive — start with two, add the rest when you need them.

Step 1: Define Your Canonical Content Format

Before writing any platform-specific code, define the content shape you'll work with internally. This is the single source of truth that every publisher transforms from.

// types.js
/**
 * @typedef {Object} CanonicalContent
 * @property {string} title
 * @property {string} bodyMarkdown - Always store in Markdown; transform on publish
 * @property {string} bodyHtml - Pre-rendered HTML for platforms that need it
 * @property {string[]} tags - Plain strings, no hashtags
 * @property {string} [canonicalUrl] - Original URL if cross-posting
 * @property {string} [featuredImageUrl]
 * @property {Object} [meta]
 * @property {string} [meta.description]
 * @property {string} [meta.slug]
 */

/**
 * @typedef {Object} PublishTarget
 * @property {string} platform - 'wordpress' | 'ghost' | 'webflow' | 'medium' | 'devto'
 * @property {Object} credentials
 * @property {Object} [options] - Platform-specific overrides
 */

Store content as Markdown internally. Every platform can accept some variant of HTML, and you can always convert Markdown → HTML. Going the other direction is a mess.

Step 2: The Publisher Core

This is the heart of the system. One function that fans out to all configured publishers in parallel.

// publisher.js
import { marked } from 'marked'; // npm install marked

import { publishToWordPress } from './publishers/wordpress.js';
import { publishToGhost } from './publishers/ghost.js';
import { publishToWebflow } from './publishers/webflow.js';
import { publishToMedium } from './publishers/medium.js';
import { publishToDevTo } from './publishers/devto.js';

const PUBLISHERS = {
  wordpress: publishToWordPress,
  ghost: publishToGhost,
  webflow: publishToWebflow,
  medium: publishToMedium,
  devto: publishToDevTo,
};

export async function publishToAll(content, targets) {
  // Pre-render Markdown to HTML once; all HTML-based platforms share this
  const contentWithHtml = {
    ...content,
    bodyHtml: marked.parse(content.bodyMarkdown),
  };

  // Run all publishers in parallel — don't await sequentially
  // Promise.allSettled never throws, even if individual publishers fail
  const publishJobs = targets.map(async (target) => {
    const publishFn = PUBLISHERS[target.platform];

    if (!publishFn) {
      return {
        platform: target.platform,
        success: false,
        error: `Unknown platform: ${target.platform}`,
      };
    }

    try {
      const result = await publishFn(contentWithHtml, target.credentials, target.options);
      return { platform: target.platform, success: true, ...result };
    } catch (err) {
      return {
        platform: target.platform,
        success: false,
        error: err.message,
        // Include retry hint if the publisher provides one
        retryAfter: err.retryAfter ?? null,
      };
    }
  });

  const settled = await Promise.allSettled(publishJobs);

  // allSettled always resolves; extract the values
  const results = Object.fromEntries(
    settled.map((s) => {
      const value = s.status === 'fulfilled' ? s.value : { success: false, error: s.reason?.message };
      return [value.platform, value];
    })
  );

  const successCount = Object.values(results).filter((r) => r.success).length;
  const status =
    successCount === targets.length ? 'success' :
    successCount === 0 ? 'failed' :
    'partial_success';

  return { status, results };
}

The key decision here: Promise.allSettled instead of Promise.all. With Promise.all, one platform failure throws and you lose all your results. With allSettled, you get granular success/failure per platform and can retry only what failed.

Step 3: The Platform Publishers

WordPress

WordPress has two API options: the legacy XML-RPC endpoint and the newer REST API (available on WordPress 4.7+). Use the REST API if you can — it's significantly cleaner.

// publishers/wordpress.js

export async function publishToWordPress(content, credentials, options = {}) {
  const { siteUrl, username, appPassword } = credentials;
  // App Passwords were added in WP 5.6 — generate one in Users → Profile
  // Format: "xxxx xxxx xxxx xxxx xxxx xxxx" (spaces included)
  const authHeader = 'Basic ' + btoa(`${username}:${appPassword}`);

  const payload = {
    title: content.title,
    content: content.bodyHtml,
    status: options.status ?? 'publish', // 'draft' for review workflows
    tags: await resolveWordPressTags(content.tags, siteUrl, authHeader),
    // WordPress requires tag IDs, not strings — resolveWordPressTags handles this
    slug: content.meta?.slug,
    excerpt: content.meta?.description,
    ...(content.featuredImageUrl && {
      featured_media: await uploadWordPressMedia(content.featuredImageUrl, siteUrl, authHeader),
    }),
  };

  const response = await fetch(`${siteUrl}/wp-json/wp/v2/posts`, {
    method: 'POST',
    headers: {
      'Authorization': authHeader,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`WordPress API error: ${err.message} (${err.code})`);
  }

  const post = await response.json();
  return { url: post.link, postId: post.id };
}

async function resolveWordPressTags(tags, siteUrl, authHeader) {
  // WordPress needs tag IDs, not strings — create tags that don't exist yet
  const tagIds = await Promise.all(
    tags.map(async (tagName) => {
      // Try to find existing tag first
      const searchRes = await fetch(
        `${siteUrl}/wp-json/wp/v2/tags?search=${encodeURIComponent(tagName)}`,
        { headers: { Authorization: authHeader } }
      );
      const existing = await searchRes.json();

      if (existing.length > 0) return existing[0].id;

      // Create new tag if it doesn't exist
      const createRes = await fetch(`${siteUrl}/wp-json/wp/v2/tags`, {
        method: 'POST',
        headers: { Authorization: authHeader, 'Content-Type': 'application/json' },
        body: JSON.stringify({ name: tagName }),
      });
      const newTag = await createRes.json();
      return newTag.id;
    })
  );
  return tagIds;
}

WordPress gotcha: App Passwords are different from your login password. Go to Users → Your Profile → Application Passwords and generate one specifically for your publishing integration. Your regular password won't work with the REST API in most configurations.

Ghost

Ghost's Admin API uses JWT authentication with a short expiry. You can't use a static bearer token — you have to generate a new JWT per request.

// publishers/ghost.js
import crypto from 'crypto';

export async function publishToGhost(content, credentials, options = {}) {
  const { adminUrl, adminApiKey } = credentials;
  // Admin API Key format from Ghost Admin: "key_id:secret" — split on the colon
  const [keyId, secret] = adminApiKey.split(':');

  const jwt = generateGhostJWT(keyId, secret);

  // Ghost uses Mobiledoc OR Lexical depending on version
  // Sending HTML with `html` field works for Ghost 5.x with the html conversion flag
  const payload = {
    posts: [{
      title: content.title,
      html: content.bodyHtml,
      status: options.status ?? 'published',
      tags: content.tags.map((name) => ({ name })), // Ghost accepts tag names directly
      custom_excerpt: content.meta?.description,
      canonical_url: content.canonicalUrl,
      ...(content.featuredImageUrl && { feature_image: content.featuredImageUrl }),
    }],
  };

  const response = await fetch(`${adminUrl}/ghost/api/admin/posts/?source=html`, {
    method: 'POST',
    headers: {
      'Authorization': `Ghost ${jwt}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Ghost API error: ${err.errors?.[0]?.message}`);
  }

  const result = await response.json();
  const post = result.posts[0];
  return { url: post.url, postId: post.id };
}

function generateGhostJWT(keyId, secret) {
  // Ghost uses a specific JWT structure — don't try to use a generic JWT library
  const now = Math.floor(Date.now() / 1000);
  const header = { alg: 'HS256', typ: 'JWT', kid: keyId };
  const payload = { iat: now, exp: now + 300, aud: '/admin/' }; // 5-minute expiry

  const encode = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
  const headerB64 = encode(header);
  const payloadB64 = encode(payload);
  const signingInput = `${headerB64}.${payloadB64}`;

  const signature = crypto
    .createHmac('sha256', Buffer.from(secret, 'hex'))
    .update(signingInput)
    .digest('base64url');

  return `${signingInput}.${signature}`;
}

Ghost gotcha: The ?source=html query param is critical. Without it, Ghost tries to parse your HTML as Mobiledoc and the content will be empty. This burned me for two days.

Webflow

Webflow is the most setup-intensive because it requires knowing your Collection ID and the field schema before publishing anything.

// publishers/webflow.js

export async function publishToWebflow(content, credentials, options = {}) {
  const { apiToken, collectionId } = credentials;
  // collectionId: get from Webflow Dashboard → CMS → your blog collection → Settings
  // The ID is in the URL: webflow.com/design/.../cms/[collectionId]

  // Webflow field names depend on YOUR collection schema
  // These are the defaults — override via options.fieldMap if yours are different
  const fieldMap = {
    title: 'name',         // Webflow always uses 'name' as the required display field
    body: 'post-body',     // Whatever you named your rich text field
    slug: 'slug',
    description: 'post-summary',
    tags: 'tags',
    featuredImage: 'main-image',
    ...options.fieldMap,
  };

  const fields = {
    [fieldMap.title]: content.title,
    [fieldMap.body]: content.bodyHtml,
    [fieldMap.slug]: content.meta?.slug ?? slugify(content.title),
    [fieldMap.description]: content.meta?.description ?? '',
  };

  const response = await fetch(
    `https://api.webflow.com/v2/collections/${collectionId}/items/live`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ fieldData: fields }),
    }
  );

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Webflow API error: ${err.message} — field: ${err.code}`);
  }

  const item = await response.json();
  // /live endpoint publishes immediately; use /items (without /live) for drafts
  return { itemId: item.id };
}

function slugify(title) {
  return title
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-|-$/g, '');
}

Webflow gotcha: The /live suffix on the endpoint publishes immediately. Without it, you create a draft that only exists in staging. I spent an embarrassing amount of time wondering why my published items weren't showing up on the live site.

Medium

Medium's API is officially deprecated-ish — they stopped accepting new OAuth app registrations but still support Integration Tokens for personal publishing.

// publishers/medium.js

export async function publishToMedium(content, credentials, options = {}) {
  const { integrationToken } = credentials;
  // Get from medium.com/me/settings → Integration Tokens

  // First, get your user ID — required for the posts endpoint
  const userRes = await fetch('https://api.medium.com/v1/me', {
    headers: { Authorization: `Bearer ${integrationToken}` },
  });

  if (!userRes.ok) throw new Error('Medium auth failed — check your integration token');

  const { data: user } = await userRes.json();

  const payload = {
    title: content.title,
    contentFormat: 'html', // 'markdown' also works but HTML renders more reliably
    content: content.bodyHtml,
    tags: content.tags.slice(0, 5), // Medium enforces a 5-tag limit
    canonicalUrl: content.canonicalUrl,
    publishStatus: options.status ?? 'public', // 'draft' | 'public' | 'unlisted'
  };

  const response = await fetch(`https://api.medium.com/v1/users/${user.id}/posts`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${integrationToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Medium API error: ${err.errors?.[0]?.message}`);
  }

  const { data: post } = await response.json();
  return { url: post.url, postId: post.id };
}

Medium gotcha: They silently truncate tags beyond 5. If you pass 8 tags, the API succeeds but only the first 5 appear. The .slice(0, 5) is defensive, not cosmetic.

Dev.to

The cleanest API of the five. API key auth, straightforward payload, good documentation.

// publishers/devto.js

export async function publishToDevTo(content, credentials, options = {}) {
  const { apiKey } = credentials;
  // Get from dev.to/settings/extensions → DEV Community API Keys

  const payload = {
    article: {
      title: content.title,
      body_markdown: content.bodyMarkdown, // Dev.to wants Markdown, not HTML
      published: options.status !== 'draft',
      tags: content.tags
        .slice(0, 4) // Dev.to enforces a 4-tag limit
        .map((t) => t.toLowerCase().replace(/[^a-z0-9]/g, '')), // tags: lowercase, alphanumeric only
      canonical_url: content.canonicalUrl,
      description: content.meta?.description,
      ...(content.featuredImageUrl && { main_image: content.featuredImageUrl }),
    },
  };

  const response = await fetch('https://dev.to/api/articles', {
    method: 'POST',
    headers: {
      'api-key': apiKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (response.status === 429) {
    // Rate limit: 10 articles per 30 seconds on free accounts
    const retryAfter = parseInt(response.headers.get('retry-after') ?? '60', 10);
    const err = new Error('Dev.to rate limit exceeded');
    err.retryAfter = retryAfter; // Bubble up to the retry system
    throw err;
  }

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Dev.to API error: ${JSON.stringify(err)}`);
  }

  const article = await response.json();
  return { url: article.url, articleId: article.id };
}

Dev.to gotcha: Tags must be lowercase and contain only letters and numbers — no hyphens, no spaces. "web-dev" becomes "webdev". Pass them through the sanitizer above or they'll silently fail validation.

Step 4: The HTTP Endpoint

Wire everything together with a simple Express endpoint.

// server.js
import express from 'express';
import { publishToAll } from './publisher.js';

const app = express();
app.use(express.json({ limit: '2mb' })); // Articles can get big with embedded code

app.post('/publish', async (req, res) => {
  const { content, targets } = req.body;

  // Basic validation — add more for production
  if (!content?.title || !content?.bodyMarkdown) {
    return res.status(400).json({ error: 'content.title and content.bodyMarkdown are required' });
  }

  if (!Array.isArray(targets) || targets.length === 0) {
    return res.status(400).json({ error: 'targets must be a non-empty array' });
  }

  try {
    const result = await publishToAll(content, targets);
    // Return 207 Multi-Status for partial success — it's the correct HTTP status here
    const statusCode = result.status === 'failed' ? 500 : result.status === 'partial_success' ? 207 : 200;
    return res.status(statusCode).json(result);
  } catch (err) {
    // This only fires if publishToAll itself throws — individual platform errors are caught inside
    return res.status(500).json({ error: err.message });
  }
});

app.listen(3000, () => console.log('Publisher running on :3000'));

A sample request to test all five platforms:

curl -X POST http://localhost:3000/publish \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "title": "How I Optimized Our Node.js Queue",
      "bodyMarkdown": "## The Problem\n\nAt 500 concurrent jobs...",
      "tags": ["nodejs", "javascript", "performance", "webdev"],
      "meta": {
        "description": "A practical guide to Node.js queue optimization",
        "slug": "nodejs-queue-optimization"
      }
    },
    "targets": [
      {
        "platform": "wordpress",
        "credentials": { "siteUrl": "https://yourblog.com", "username": "admin", "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx" }
      },
      {
        "platform": "devto",
        "credentials": { "apiKey": "your_devto_api_key" }
      }
    ]
  }'

What Can Go Wrong

Rate limits cascade. If you're publishing high volume, you'll hit rate limits on Dev.to (10/30s) and Medium first. The retryAfter field on the error lets you implement a per-platform retry queue. Don't retry all platforms when only one rate-limited — that's how you get banned.

Ghost JWT clock drift. Ghost's JWT validation is strict about the iat and exp fields. If your server clock is off by more than a few seconds from Ghost's server, you'll get mysterious 401s. Add NTP sync to your server checklist if you're running this in production.

Webflow field mismatches. If your Webflow collection has required fields you're not supplying, the API returns a 400 with a cryptic field name error. Before implementing, dump your collection schema: GET https://api.webflow.com/v2/collections/{collectionId} and map every required field.

WordPress multisite installs. If your WordPress is a multisite network, the API path changes. Instead of /wp-json/wp/v2/posts, it becomes /site-path/wp-json/wp/v2/posts. The base URL you pass in credentials needs to include the subsite path.

Medium's canonicalUrl field. Medium strips HTTP/HTTPS from canonical URLs if they point to Medium itself. If you're cross-posting from another platform, always set canonicalUrl to the original source URL to avoid duplicate content penalties. The API accepts it but doesn't validate it — a wrong canonical URL won't cause an error, it'll just quietly hurt your SEO.

Where to Take This

The implementation above covers the publish path. In PostAll, this publisher sits behind two more layers I haven't covered here:

A retry queue. When platforms return rate-limit errors or 5xx responses, failed publish jobs go into a Redis-backed retry queue with exponential backoff. Platform-specific retryAfter hints from the error object feed directly into the delay calculation.

A format validator. Before hitting any platform API, content runs through a validator that checks Markdown for broken image links, missing alt text, and code blocks without language identifiers. Catching these before publish is faster than debugging broken posts after the fact.

Both of those are topics for separate posts. If you want to see either covered next, drop it in the comments.

The complete source for this publisher — with a few more error-handling details I cut for brevity — is at: github.com/your-handle/multi-platform-publisher. If it saves you the 3 days it took me to figure out Ghost's JWT implementation, a star would be appreciated.

What platforms are you publishing to that I missed? LinkedIn articles and Hashnode are both on my list — curious if anyone's built a reliable LinkedIn publisher, since their API for articles is historically finicky.

PostAll is a content automation platform I'm building for teams that publish at scale. If the multi-platform publishing problem is one you're actively dealing with, I write about the architecture behind it here regularly.

I Analyzed 1,000 AI-Generated Blog Posts for Quality. Here's the Data.

Aakash Gour — Thu, 28 May 2026 06:16:31 +0000

Last year, I was doing something that felt increasingly absurd: manually reading AI-generated content to decide if it was "good enough."

PostAll — the content automation tool I've been building — was producing hundreds of blog posts per week for clients. And I had no systematic way to evaluate quality at scale. I was spot-checking. Vibes-checking, really. That doesn't work at volume.

So I built a programmatic quality analysis pipeline, ran it over 1,000 AI-generated posts, and let the numbers tell me what my gut was missing.

The findings surprised me. A few of them genuinely changed how I think about AI content quality.

What I Actually Measured

First, a definition of terms, because "quality" is almost meaninglessly vague in this space.

I broke quality into five measurable dimensions:

Readability — Flesch-Kincaid grade level and reading ease score
Keyword density — Target keyword frequency and distribution across the post
Grammar error rate — Errors per 1,000 words, caught via LanguageTool's API
Factual accuracy — Claims that could be verified programmatically (dates, statistics, named entities cross-referenced against a knowledge base)
Structural consistency — Presence of expected elements: intro hook, subheadings, conclusion, CTA

I used 1,000 posts across three categories: SaaS product descriptions, long-form "how-to" articles (1,200–2,000 words), and listicles (500–900 words). All were generated by PostAll using GPT-4o, with various prompting strategies.

The Setup

The analysis pipeline isn't complicated, but the piece that makes it useful is the batch processing layer:

import anthropic
import language_tool_python
import textstat
from dataclasses import dataclass
from typing import Optional
import json

@dataclass
class QualityReport:
    post_id: str
    flesch_reading_ease: float
    flesch_kincaid_grade: float
    grammar_errors_per_1000_words: float
    keyword_density: float
    structural_score: int  # 0–5 based on element presence
    flagged_claims: list[str]
    overall_score: float

tool = language_tool_python.LanguageTool('en-US')

def analyze_readability(text: str) -> dict:
    return {
        "flesch_reading_ease": textstat.flesch_reading_ease(text),
        "flesch_kincaid_grade": textstat.flesch_kincaid_grade(text),
    }

def analyze_grammar(text: str) -> float:
    matches = tool.check(text)
    word_count = len(text.split())
    # Filter out style suggestions — we only care about errors
    errors = [m for m in matches if m.ruleId not in STYLE_RULE_IDS]
    return (len(errors) / word_count) * 1000

def analyze_structure(text: str, expected_elements: list[str]) -> int:
    score = 0
    lowered = text.lower()
    for element in expected_elements:
        if element in lowered:
            score += 1
    return score

The STYLE_RULE_IDS exclusion is important. LanguageTool flags passive voice, comma splices, and other style choices that are sometimes intentional. Without filtering, style suggestions inflate the error count and make decent posts look broken.

For factual accuracy, I used a two-step approach: first, extract named entities and statistics using Claude, then cross-reference against a curated knowledge base for the client's domain. This doesn't catch everything — but it catches the most common failure modes (wrong dates, made-up statistics, hallucinated product names).

def extract_verifiable_claims(post_text: str) -> list[str]:
    client = anthropic.Anthropic()

    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": f"""Extract all factual claims from this post that could be verified:
            - Statistics with numbers
            - Named products, companies, or people with specific attributes
            - Dates and years
            - Prices or measurements

            Return as a JSON array of strings. Only include claims, not opinions.

            Post:
            {post_text}"""
        }]
    )

    try:
        claims = json.loads(response.content[0].text)
        return claims
    except json.JSONDecodeError:
        # Claude occasionally adds preamble even when asked not to
        # This is the real-world version, not the happy path
        return []

The Data

Here's what came back after running 1,000 posts through the pipeline.

Readability

Post Type	Avg. Flesch Reading Ease	Avg. FK Grade Level
Product descriptions	52.3	11.2
How-to articles	44.7	13.1
Listicles	61.8	9.4

For context: a score of 60–70 on the Flesch scale is considered "standard" — roughly plain English. A grade level of 8 is the target for most consumer-facing content.

The problem: the how-to articles were reading at a college level on average. When I looked at the worst offenders (grade 16+), the pattern was consistent — they were posts where I'd given the model a technically dense brief without explicitly requesting plain language output.

The fix was embarrassingly simple:

READABILITY_INSTRUCTION = """
Write at a 7th to 8th grade reading level (Flesch-Kincaid).
Use short sentences. Prefer common words over technical jargon
unless the term is essential and explained on first use.
Aim for a Flesch Reading Ease score above 60.
"""

Adding this to the system prompt dropped the average grade level from 13.1 to 9.4 across the how-to category. One instruction. Measurable improvement.

Grammar Error Rate

Average across all 1,000 posts: 2.1 errors per 1,000 words.

For human-written content, industry benchmarks sit around 3–5 errors per 1,000 words for first drafts. So the AI was actually outperforming average human first drafts on raw grammar.

But here's what the aggregate hides: the distribution was bimodal. 80% of posts had fewer than 1 error per 1,000 words. The remaining 20% had 8+ errors — almost always in posts that exceeded 1,500 words and involved a complex prompt with multiple constraints.

The hypothesis: when the model is managing a lot of constraints simultaneously (tone + structure + keyword requirements + specific claims to include), grammar degrades. It's spending its "attention" elsewhere.

My mitigation was to break complex posts into two passes: structure and content first, then a second pass focused specifically on prose quality and grammar. Error rate in the high-complexity category dropped from 9.3 to 2.8.

Keyword Density

Target range for SEO: 1–2% density for the primary keyword.

Density Range	% of Posts
Under 0.5% (keyword stuffing avoided, but too thin)	23%
0.5–1% (acceptable)	31%
1–2% (target range)	29%
2–3% (slightly over-optimized)	12%
Over 3% (keyword stuffed, will hurt rankings)	5%

The surprise: I expected over-stuffing to be the main failure mode. Turns out under-stuffing was almost 5x more common. The model was avoiding the keyword in an apparent attempt to sound natural — which is good instinct but overcorrected.

This one is prompt-sensitive. Explicitly specifying "include the primary keyword [X] approximately 8–12 times in a 1,000-word post" got the distribution into the target range for 74% of subsequent posts.

Structural Consistency

I scored each post on five structural elements:

Hook in the opening paragraph (first 100 words)
At least two H2 subheadings
One concrete example or case study
Conclusion section
Call to action

Score	% of Posts
5/5	38%
4/5	41%
3/5	15%
2/5 or below	6%

The most commonly missing element: the hook. 34% of posts opened with a definition, a generic statement about the topic, or the phrase "In today's digital landscape." (I have seen "In today's digital landscape" more times than I have seen sunrises. The model defaults to it under pressure.)

The second most commonly missing element: the concrete example. The model would describe a concept clearly but not ground it in a specific scenario. This is fixable with one line in the prompt: "Include at least one specific real-world example or case study."

Factual Accuracy

This is the one that should concern you.

Of the 1,000 posts, the pipeline flagged 147 posts (14.7%) as containing at least one unverifiable or contradicted claim.

Common failure types:

Outdated statistics — citing research from 3–5 years ago as "recent" (43 posts)
Made-up product features — describing a competitor's product with features it doesn't have (31 posts)
Hallucinated citations — references to studies or reports that don't exist (29 posts)
Wrong dates — misattributing when a company was founded or a product was launched (44 posts)

The hallucinated citations were the most dangerous. They looked authoritative. They had the right format. The study just didn't exist.

What This Changed in PostAll

Three concrete changes came out of this analysis:

1. Readability is now a post-generation check, not just a prompt instruction.

Every post runs through textstat before it's delivered. If the Flesch-Kincaid grade is above 10, the post goes back for a rewrite pass with an explicit readability constraint.

2. Factual claims trigger a verification flag.

Any post with more than three verifiable claims (per the Claude extraction step above) gets flagged for human review before delivery. This catches the hallucinated-citation failure mode without requiring human review of everything.

3. Two-pass generation for anything over 1,200 words.

Pass one: structure and content. Pass two: prose quality, grammar, and consistency check. The compute cost is real — roughly 2x token usage for long-form. The error rate improvement justified it.

What I'd Do Differently

I'd instrument this from day one, not month six.

The manual spot-checking I was doing before the pipeline wasn't just slow — it was inconsistent. I'd catch a grammar issue in one post and miss a hallucinated citation in the next. The programmatic check is less nuanced than human review, but it's consistent, which turns out to matter more at volume.

I'd also add a semantic coherence score earlier. Right now I can tell you a post has a grade-8 reading level and 1.3% keyword density. I can't tell you programmatically whether the argument in the post actually holds together. That's the next frontier.

The One Finding I Keep Coming Back To

Grammar is not the quality problem.

Every client who asks me "is the AI content good?" is thinking about grammar errors. The data says grammar errors are rare — and when they appear, they're predictable and fixable.

The real quality problems are factual accuracy and structural consistency. A post with perfect grammar that cites a study that doesn't exist is not a quality post. A post that opens with "In today's digital landscape" and never grounds the argument in a specific example is not a quality post.

You can't catch either of those by reading a paragraph. You need to measure them.

The pipeline code is on GitHub — link in my bio. If you're building content automation and haven't instrumented quality yet, this is the starting point I'd recommend.

What's your approach to quality scoring AI content at scale? Especially curious if anyone's cracked semantic coherence programmatically — that's the gap I haven't solved.

How to Build a Content Similarity Checker to Avoid Duplicate AI Output

Aakash Gour — Mon, 25 May 2026 05:47:46 +0000

When I started running bulk content generation jobs in PostAll, I hit a problem I didn't expect.

Not hallucinations. Not rate limits. Duplicates.

Not copy-paste duplicates — subtle ones. Two blog posts about "email marketing tips" that were structurally identical: same three sections, same examples, same conclusion, different sentences. The kind of thing that looks fine until you read them back to back and realize the AI just remixed the same underlying content.

At 10 articles, you catch this manually. At 500, you don't.

Here's the exact similarity checker I built to fix it — using OpenAI embeddings and cosine similarity, with a threshold you can tune to your use case.

Why String Matching Doesn't Cut It

My first instinct was to compare outputs with something simple. Calculate the Levenshtein distance between strings, flag anything above a similarity score. Shipped it in an afternoon.

It failed immediately.

Two articles can share 0% of their exact words and still be meaningfully duplicate content. "Email marketing boosts your open rates" and "Sending better emails increases how many people read them" are semantically identical — string matching treats them as completely different.

What you actually need is semantic similarity: are these two pieces of content saying the same thing, regardless of how the words are arranged?

That's what embeddings are for.

How Embeddings Work (The Part That Actually Matters)

An embedding is a vector — a list of numbers — that represents the meaning of a piece of text. OpenAI's text-embedding-3-small model converts any text into a 1536-dimensional vector.

Here's the useful property: texts with similar meaning produce vectors that point in similar directions in that 1536-dimensional space. Texts with different meaning point in different directions.

Cosine similarity measures the angle between two vectors. An angle of 0° (cosine similarity = 1.0) means identical direction — same meaning. An angle of 90° (cosine similarity = 0) means orthogonal — completely unrelated content.

In practice:

0.95+: Near-duplicate. Same content, slight rewording.
0.85–0.95: Very similar. Same topic and angle, different structure.
0.70–0.85: Related content. Same topic, meaningfully different angle.
Below 0.70: Different enough. Probably fine to publish both.

Your threshold depends on your use case. I'll come back to this.

The Implementation

1. Set Up the Embedding Client

// similarity-checker.js
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// text-embedding-3-small: 1536 dimensions, $0.02/1M tokens
// text-embedding-3-large: 3072 dimensions, $0.13/1M tokens
// For content dedup, small is accurate enough and ~6x cheaper
const EMBEDDING_MODEL = "text-embedding-3-small";

2. Get an Embedding for a Piece of Content

async function getEmbedding(text) {
  // Truncate at ~8000 tokens — embeddings model limit is 8191
  // For articles, take first 6000 chars: captures topic, angle, structure
  // without padding from conclusion boilerplate
  const truncated = text.slice(0, 6000);

  const response = await openai.embeddings.create({
    model: EMBEDDING_MODEL,
    input: truncated,
  });

  return response.data[0].embedding; // array of 1536 floats
}

Why truncate at 6000 chars instead of sending the full article?

Two reasons. First, the model has an 8191-token limit. Second, and more importantly: the first ~1500 words of an article carry almost all of its semantic fingerprint — the topic, angle, key claims. The conclusion is usually boilerplate. Truncating early makes the check faster and, in my testing, more accurate for detecting duplicates.

3. Calculate Cosine Similarity

function cosineSimilarity(vecA, vecB) {
  // Both vectors must be the same length (1536 for text-embedding-3-small)
  if (vecA.length !== vecB.length) {
    throw new Error(`Vector length mismatch: ${vecA.length} vs ${vecB.length}`);
  }

  let dotProduct = 0;
  let magnitudeA = 0;
  let magnitudeB = 0;

  for (let i = 0; i < vecA.length; i++) {
    dotProduct += vecA[i] * vecB[i];
    magnitudeA += vecA[i] * vecA[i];
    magnitudeB += vecB[i] * vecB[i];
  }

  magnitudeA = Math.sqrt(magnitudeA);
  magnitudeB = Math.sqrt(magnitudeB);

  if (magnitudeA === 0 || magnitudeB === 0) return 0;

  return dotProduct / (magnitudeA * magnitudeB);
}

This is the full cosine similarity formula — no library needed. It runs in O(n) where n is the vector dimension (1536), so it's fast for individual comparisons.

4. Check One Article Against a Library

async function checkForDuplicates(newContent, existingArticles, threshold = 0.88) {
  const newEmbedding = await getEmbedding(newContent);
  const duplicates = [];

  for (const article of existingArticles) {
    // Skip re-embedding if you've cached embeddings (you should — see below)
    const existingEmbedding = article.embedding ?? await getEmbedding(article.content);

    const similarity = cosineSimilarity(newEmbedding, existingEmbedding);

    if (similarity >= threshold) {
      duplicates.push({
        articleId: article.id,
        title: article.title,
        similarity: Math.round(similarity * 100) / 100,
      });
    }
  }

  // Sort by similarity descending so the most egregious duplicate is first
  duplicates.sort((a, b) => b.similarity - a.similarity);

  return {
    isDuplicate: duplicates.length > 0,
    matches: duplicates,
    newEmbedding, // return so caller can cache it
  };
}

5. Putting It Together for a Bulk Job

async function processBulkGeneration(articles) {
  const results = [];
  const processedArticles = []; // grows as we process

  for (const article of articles) {
    const { isDuplicate, matches, newEmbedding } = await checkForDuplicates(
      article.content,
      processedArticles,
      0.88
    );

    if (isDuplicate) {
      results.push({
        ...article,
        status: "duplicate",
        duplicateOf: matches[0], // most similar match
        action: "needs_revision",
      });
    } else {
      results.push({
        ...article,
        status: "unique",
        action: "ready_to_publish",
      });

      // Only add non-duplicates to the comparison pool
      // Adding duplicates would penalize articles similar to a bad article
      processedArticles.push({
        id: article.id,
        title: article.title,
        content: article.content,
        embedding: newEmbedding, // cache it — never re-embed the same content
      });
    }

    // Rate limit: embeddings API allows ~3000 RPM on tier 1
    // For bulk jobs, 50ms between requests keeps you well under
    await new Promise((resolve) => setTimeout(resolve, 50));
  }

  return results;
}

The Part That Bit Me: Caching Embeddings

The first version of this had no caching. For a job of 200 articles:

Embedding each article: 200 API calls
Checking each article against all previous: up to 200 × 199 / 2 = 19,900 comparisons

The comparisons are free — they're just math. But I was re-embedding articles every time I ran the checker, even articles I'd already processed.

At $0.02 per million tokens, re-embedding 200 articles (~500 tokens each) costs almost nothing. But at scale, with a persistent library of 10,000+ articles to check against, you want to store embeddings in your database and retrieve them directly.

// With a database — pseudocode for the storage layer
// but the retrieval pattern is what matters

async function getOrCreateEmbedding(articleId, content, db) {
  // Check if we already have this embedding stored
  const cached = await db.query(
    "SELECT embedding FROM articles WHERE id = $1 AND embedding IS NOT NULL",
    [articleId]
  );

  if (cached.rows[0]) {
    // Parse back from JSON — most DBs store vectors as JSON arrays
    return JSON.parse(cached.rows[0].embedding);
  }

  // Generate and store
  const embedding = await getEmbedding(content);
  await db.query(
    "UPDATE articles SET embedding = $1 WHERE id = $2",
    [JSON.stringify(embedding), articleId]
  );

  return embedding;
}

If you're on Postgres, the pgvector extension handles this natively, including fast ANN (approximate nearest neighbor) search so you're not doing a full scan of 10,000 embeddings for every new article.

Tuning the Threshold

I ran 50 article pairs through manual review to calibrate the threshold for PostAll's use case. Here's what I found at each level:

0.95+: True duplicates only. Same article, rewritten paragraph by paragraph. This catches almost nothing useful because it's too strict for AI-generated content, which tends to vary more than you'd expect even when covering the same topic.

0.88–0.92: The sweet spot for "same content, different words." Two articles about "onboarding email sequences" that cover the same three tactics in the same order. Definitely shouldn't both be published.

0.80–0.88: Similar topic and angle, but meaningfully different. An article about "onboarding email sequences for SaaS" vs. "onboarding email sequences for e-commerce" might land here. Depending on your use case, this might be a flag-for-review rather than an automatic rejection.

Below 0.80: Different enough to publish regardless of topic overlap.

My recommendation: start at 0.88, manually review your first 20 flags, and adjust from there. The threshold is highly dependent on how diverse your content topics are and how much variation your generation prompts produce.

What Can Go Wrong

Short content produces unreliable embeddings. A 50-word product description doesn't give the model enough signal. I set a minimum of 200 words before running similarity checks — anything shorter gets flagged for manual review instead.

All your content comes back as similar. This usually means your generation prompts are too rigid. If every prompt says "write in a professional, informative tone with three sections and a clear conclusion," the AI will produce structurally similar content regardless of topic. The similarity checker is revealing a prompt diversity problem, not a bug in the checker.

Embeddings drift if you switch models. text-embedding-3-small and text-embedding-ada-002 produce incompatible vector spaces. If you switch embedding models, you need to re-embed your entire library. Store which model generated each embedding alongside the vector.

The check is O(n) per article against your existing library. At 10,000 articles, checking a new article requires 10,000 cosine similarity calculations. That's still fast (under 100ms in my testing), but if you're checking 500 new articles against a library of 50,000, consider pgvector's HNSW index for approximate nearest neighbor search instead of the brute-force approach above.

The Complete Script (Copy-Paste Ready)

// content-similarity-checker.js
// Requires: openai npm package, OPENAI_API_KEY env var

import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function getEmbedding(text) {
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: text.slice(0, 6000),
  });
  return response.data[0].embedding;
}

function cosineSimilarity(vecA, vecB) {
  let dot = 0, magA = 0, magB = 0;
  for (let i = 0; i < vecA.length; i++) {
    dot += vecA[i] * vecB[i];
    magA += vecA[i] ** 2;
    magB += vecB[i] ** 2;
  }
  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
}

export async function checkSimilarity(newContent, library, threshold = 0.88) {
  if (newContent.length < 200) {
    return { status: "too_short", isDuplicate: false, matches: [] };
  }

  const embedding = await getEmbedding(newContent);
  const matches = library
    .map((item) => ({
      ...item,
      similarity: cosineSimilarity(embedding, item.embedding),
    }))
    .filter((item) => item.similarity >= threshold)
    .sort((a, b) => b.similarity - a.similarity);

  return {
    status: matches.length > 0 ? "duplicate" : "unique",
    isDuplicate: matches.length > 0,
    matches,
    embedding, // cache this
  };
}

Usage:

import { checkSimilarity } from "./content-similarity-checker.js";

// Your existing articles with cached embeddings
const library = await db.query("SELECT id, title, embedding FROM articles");

const result = await checkSimilarity(newArticleContent, library.rows);

if (result.isDuplicate) {
  console.log(`Duplicate detected (${result.matches[0].similarity} similarity)`);
  console.log(`Most similar to: "${result.matches[0].title}"`);
} else {
  // Safe to publish — cache the embedding
  await db.query("UPDATE articles SET embedding = $1 WHERE id = $2", [
    JSON.stringify(result.embedding),
    newArticle.id,
  ]);
}

What I'd Add Next

The similarity checker catches what was already generated. It doesn't prevent duplicate content from being generated in the first place.

The next layer I'm building: before generating content on a topic, check the existing library for similar topics. If something with 0.88+ similarity already exists, either skip the generation or pass the existing article's key points to the prompt as a negative constraint: "Do not cover these points — they're already addressed in our existing content."

That closes the loop. Instead of catching duplicates after generation, you're steering generation away from duplication upfront.

The full code is on GitHub: [link to repo]. If you're using pgvector and want the schema for storing and querying embeddings at scale, the README covers that too.

What threshold did you land on for your use case? I'm curious whether the 0.88 default holds up across different content types — drop it in the comments.