Reference
Content quality pipeline
The Keyword-to-Blog API never returns a raw first draft. Every POST /v1/generate and POST /v1/jobs request goes through one of two paths, depending on the topic. In both, deterministic checks decide what is good enough, and the result is reported on every article in quality.
Facts-first path (most requests)
Used for every topic that doesn’t depend on current information (see below). The writer is never allowed to fill gaps from general knowledge. Specifics come from a fact sheet built from your own URL, or they don’t appear at all.
- Fact sheet (requests with a
targetUrl). On every request, with nothing cached, the page is read, possibly with a few linked pages on the same site. Reading is restricted to exactly the hostname you sent. Every fact comes with a verbatim quote, and the quote must really appear in the fetched page text for the fact to be kept. The brand name is spelled the way its own pages spell it. If the page can’t be read (one retry), the article is written as if there were no URL, and the problem is reported inquality.qa.warnings. - No URL, no fact sheet. Without a
targetUrl, every specific claim (a number, price, plan, policy or named feature) counts as unsupported and is removed, so the article stays general. - One draft is written from the fact sheet, with each sentence that uses a fact tagged by that fact’s id. Tags are stripped before publishing.
- Deterministic fixes and the universal gates (below) run. Contradicted and unsupported claim sentences are removed, brand casing is corrected, extra brand mentions are replaced, and excess hedge sentences and boilerplate openers are dropped. Editorial checks (generic intros, slug format, duplicate headings…) also run, and their mechanical fixes are applied.
- If a blocking gate still fails, up to 2 targeted repair passes run. Each is told exactly which gates failed and which sentences were removed, and each result is checked again.
- The best attempt is always returned. If a gate still fails, the response says so with
quality.status: "fail"andquality.qa.failingGatesinstead of an error. A contradicted claim is never shipped, because it is removed on every attempt.
Timing: a request with a URL typically takes 60–110 seconds end to end, because the page is read every time. Use POST /v1/jobs if you can’t hold a connection that long.
Universal quality gates
These decide quality.qa.pass for every article. There is no word-count or length gate. Content is never rejected or cut for its length.
| Gate | Rule |
|---|---|
| body.present | The article has body text. Not a length rule: it fails only when removing claims left nothing. |
| claims.contradicted | 0. A claim that disagrees with the fact sheet is always removed, never shipped. |
| claims.unsupported | At most 2 published. In practice unsupported specific claims are removed. Without a URL, every specific claim is unsupported. |
| hedges.per1000 | At most 8 hedge words (typically, often, may, might, could, likely…) per 1,000 words. A forecast attributed to the publisher of a cited fact (“Ofcom expects…”) doesn’t count. |
| keyword.density | Primary keyword phrase (the first keyword) at most 0.8% of body words. |
| keyword.perParagraph | Primary keyword phrase at most once per paragraph or list item. |
| brand.density / brand.perParagraph | With a fact sheet: the brand name counted separately, under the same caps (0.8%, once per paragraph). Content-token review and offers articles allow up to 1.8% and two mentions in a paragraph of 60+ words; analysis articles 1.0%, and the rule’s brand at most 40% of all brand mentions (brand.share); keyword caps never change. |
| brand.casing | With a fact sheet: the brand spelled exactly as its own pages spell it (e.g. “iD Mobile”, never “Idmobile”). |
| openers.boilerplate | No paragraph opens with “This guide…”, “In this article…”, “Whether you’re…”, “In today’s…”, “In the world of…”, “With so many options…” or similar. Sentences claiming hands-on testing (“we tested”) are always removed. |
| figures.sourced | With a fact sheet: at least 5 distinct concrete figures that match facts. |
| title.recycled | No stock title formula, and not the same formula as one of your API key’s recent titles. |
| sources.integrity | News-grounded articles only: every claim traces back to the validated news sources. |
| facts.available / editorial.checks / keyword.present | Informational, not blocking: whether a fact sheet was used, the editorial checks’ findings, and whether the keyword appears at all. |
News-grounded path (topics that depend on current information)
A request is routed here automatically when its topic or keywords contain any of these words or phrases (case-insensitive, including inside longer words):
price, pricing, cost, version, release, update, law, regulation, policy, statistics, latest, current, news, market, trend, trending, breaking, announcement, recent, recently, today, this year
- Recent news coverage is retrieved from several independent news sources in parallel. One source failing never blocks the others.
- Articles are deduplicated and validated. Each must have been published within the last 7 days with a real, parseable date, be genuinely relevant to the request, meet basic quality bars (valid URL, real title and text), and be free of unresolved conflicts. Sources reporting contradicting figures for the same story are excluded rather than guessed between.
- If there isn’t enough evidence, retrieval retries with a broader query, up to 3 attempts in total. The 7-day window is never relaxed. If all 3 attempts fail, the request fails with
SOURCE_VALIDATION_FAILEDand no article is written. - Once validated, the source set is locked and the article is written once from it: an independently written piece, with no copied or closely paraphrased source sentences and no facts added from general knowledge.
- Editorial checks run, plus a check that every claim traces back to the locked sources and a check for overlap with the source text. Names, technical terms and factually required numbers and dates are not counted as overlap.
- The universal gates run. If the request also has a
targetUrl, its fact sheet is built in parallel and any claim it contradicts is removed. This path has no repair pass, so the article is returned either way, andquality.qa.passtells you whether it cleared the bar.
The news articles used are listed in post.sources (title, URL, publication date) and in quality.qa.facts.sources, as metadata for your audit. They never appear in the article text or in rendered.markdown/rendered.html.
No links in published content
On both paths, the article text and the rendered markdown and HTML contain no URLs, markdown links, <a> tags, citation brackets or “Sources”/“References” sections. A final strip runs on every article, whatever the draft contained. Fact and source URLs exist only in the audit metadata described above.
Content-token articles are the one exception, and only in their rendered output: configured brand/offer links and up to three CTAs (with an affiliate disclosure), plus a Sources list built from the fact sheet’s own pages, are added after the strip. The model never writes a link; see the content tokens reference.
Editorial checks (reported, non-blocking)
These run on every article. Their findings appear in the editorial.checks gate and feed the repair passes, but they don’t decide pass or fail. The universal gates do.
| Category | What it looks for |
|---|---|
| Writing quality | Generic openings and closings, filler phrases, repetitive sentence structure or starters. |
| Originality | Duplicate or near-duplicate sentences and headings, excessive phrase repetition and, for news-grounded articles, copying from the source material. |
| Expert depth | Section length and concrete-detail markers (numbers, named specifics, examples, lists), never word count alone. |
| SEO | Title, meta description, slug format, heading structure and FAQ quality. |
| Keyword quality | Natural coverage of the primary keyword and related terms, and keyword stuffing. |
| Readability | Sentence and paragraph length, adjusted for the requested audience. |
| Structure | Section ordering and shape beyond what the JSON schema enforces. |
| Spam signals | Keyword-stuffed headings and pushy commercial language in informational content. |
This is a quality and pattern-detection system, not an “AI detector”. It never reports an AI-probability score or claims content is undetectable. It reports concrete, explainable signals instead.
Factuality: standard vs. verified
By default (factualityMode: "standard", or the field omitted), specific claims are checked against the fact sheet from your targetUrl, and removed when there is none. The article is always returned, with the result in quality.qa.
factualityMode: "verified" requires that verification actually happened: a fact sheet was built from your targetUrl, or the article was grounded in validated news coverage. When nothing could be verified (no URL, or no fact survived quote verification), the request fails with CONTENT_QUALITY_FAILED before any article is written:
{
"error": {
"code": "CONTENT_QUALITY_FAILED",
"message": "Generated content did not meet the required quality standard after automatic correction.",
"requestId": "req_77889900ee",
"details": {
"revisionCount": 0,
"overallScore": 0,
"failedCheckCodes": [
"FACTUALITY_UNVERIFIED"
]
}
}
}What you see in the response
Every article (sync response, job polling, and the job.succeeded webhook) includes quality:
status:"pass"or"fail", mirroringqa.pass.score: 0–100, a blend of the gate score and the editorial checks’ score.revisionCount: repair passes used (0–2).qualityVersion: version of the rules.qa:pass,score(gates only),failingGates,wordCount, the rawmetrics, every gate with its value and threshold, every claim found (removed ones markedomittedwith the reason), thefixesapplied, the number ofattempts,warnings, andfacts: the mode (facts,no_factsorsource_pack), the facts used with their verbatim quotes and source URLs, and the read status of each page.
{
"quality": {
"status": "pass",
"score": 93,
"revisionCount": 0,
"qualityVersion": "3.0.0",
"qa": {
"qaVersion": "engine-qa-1",
"pass": true,
"score": 95,
"failingGates": [],
"wordCount": 1120,
"metrics": {
"hedgeWords": 4,
"hedgePer1000": 3.57,
"keywordPhrase": "ai content marketing",
"keywordOccurrences": 4,
"keywordDensityPct": 0.36,
"keywordMaxPerParagraph": 1,
"brandName": "",
"brandOccurrences": 0,
"brandDensityPct": 0,
"brandMaxPerParagraph": 0,
"concreteFigures": 0,
"claims": {
"total": 1,
"supported": 0,
"unsupported": 1,
"contradicted": 0,
"omitted": 1
},
"verdictPresent": false,
"brandCasingViolations": []
},
"gates": [
{
"name": "claims.contradicted",
"pass": true,
"blocking": true,
"value": 0,
"threshold": 0
},
{
"name": "claims.unsupported",
"pass": true,
"blocking": true,
"value": 0,
"threshold": 2
},
{
"name": "hedges.per1000",
"pass": true,
"blocking": true,
"value": 3.57,
"threshold": 8
},
{
"name": "keyword.density",
"pass": true,
"blocking": true,
"value": 0.36,
"threshold": 0.8
},
{
"name": "keyword.perParagraph",
"pass": true,
"blocking": true,
"value": 1,
"threshold": 1
},
{
"name": "keyword.present",
"pass": true,
"blocking": false,
"value": 4
},
{
"name": "openers.boilerplate",
"pass": true,
"blocking": true,
"value": 0,
"threshold": 0
},
{
"name": "title.recycled",
"pass": true,
"blocking": true
},
{
"name": "facts.available",
"pass": false,
"blocking": false,
"value": "no_facts",
"detail": "no targetUrl — general article without specific prices, plans or policies"
},
{
"name": "editorial.checks",
"pass": true,
"blocking": false,
"value": 0
}
],
"claims": [
{
"id": "C1",
"text": "Most small businesses publish 4 posts a month.",
"location": "s1.p0.2",
"citedFactIds": [],
"label": "unsupported",
"reason": "states a figure (num:4) with no fact sheet to support it",
"omitted": true
}
],
"fixes": [
"omitted 1 unsupported claim sentence(s)"
],
"attempts": 1,
"warnings": [],
"facts": {
"mode": "no_facts",
"brandName": null,
"requestedUrls": [],
"allowedDomains": [],
"sources": [],
"facts": [],
"droppedQuoteMismatch": 0,
"fetchErrors": [],
"webFetch": null
}
}
}
}qa.facts also carries a diagnostic webFetch block about the page read. Treat it as informational, because its contents may change.
When a gate still fails
The article is returned anyway, with quality.status: "fail", quality.qa.pass: false and quality.qa.failingGates naming each gate that still failed after the repair passes. Your integration decides whether to publish, edit or regenerate. A simple rule is to publish only when quality.qa.pass is true.
Content-token feeds are stricter: they only deliver articles that passed every blocking quality check. A feed article that still fails is held, never queued or returned by a pull, and the scheduler retries the rule (pulls never generate). See the content tokens reference.
Sync vs. async behavior
POST /v1/generate runs the full pipeline inline and returns 200 with the article and its quality. POST /v1/jobs runs the identical pipeline in the background. A job whose gates still fail ends in status: "succeeded" with quality.status: "fail". A job ends in failed only when no article could be produced. Repair passes are internal: one request counts as one request toward your limits, plus the words in the article that was returned.