Reference
SEO formatting guide
Every generated post uses the same SEOPostV1 structure, so downstream templates and CMS imports don’t have to special-case the output. The structure is validated before a post is returned. The wording is not deterministic: the same request can produce different text.
Field-by-field structure
| Field | Purpose |
|---|---|
| title | The headline. |
| slugSuggestion | A suggested URL slug. The SEO check expects lowercase, hyphen-separated text and flags slugs over 75 characters. |
| meta.description | Search-result description. Ones longer than about 155–160 characters are flagged in the editorial checks. |
| meta.primaryKeyword | The keyword the post is optimized around. |
| outline.h1 / outline.h2 | The heading hierarchy. outline.h1 is the H1 in rendered markdown and HTML. |
| sections | Ordered blocks typed introduction, body, faq, conclusion or callout. Each has contentMarkdown, except that a callout may carry only callout.label/callout.text. Capped by constraints.maxSections. |
| faqs | Question/answer pairs, requested with constraints.includeFAQs. Optional: check before using it. |
| conclusion | The canonical closing text. Rendered markdown/HTML use this and skip the prose of any conclusion-type section, so the closing never appears twice. |
| coverageNotes.keywordCoverage | Optional. Per keyword: whether it was covered and where. |
| sources | Only on news-grounded posts: the news articles used (title, URL, date), as metadata. Never rendered. |
How request fields shape the post
- keywords: the first keyword is the primary keyword phrase. The quality gates keep it at most once per paragraph and at most 0.8% of words.
- language, region, tone, targetAudience, brandVoice, industry guide the writing. They change the wording, never the JSON structure or field names.
- targetUrl is the only source of specifics (prices, plans, policies, figures). Without it the post stays general. See the content quality pipeline.
- constraints.maxSections caps the number of sections. constraints.maxWords/minWords don’t change length: posts come back at their natural length.
- Rendered output (
rendered.markdown,rendered.html) is built frompostin this order: H1, each section with its H2 heading, a “Frequently asked questions” block whenfaqsis present, thenconclusion. It never contains links.
Complete example
A full SEOPostV1 object:
SEOPostV1
{
"title": "AI Content Marketing for Small Businesses: A Practical Starting Point",
"slugSuggestion": "ai-content-marketing-small-business",
"meta": {
"description": "A practical guide to using AI content marketing as a small business, without losing the voice your customers already trust.",
"primaryKeyword": "ai content marketing"
},
"outline": {
"h1": "AI Content Marketing for Small Businesses: A Practical Starting Point",
"h2": [
"Why small businesses are turning to AI content marketing",
"Where AI helps most, and where it doesn't",
"Keeping your brand voice consistent",
"A simple weekly workflow",
"Frequently asked questions"
]
},
"sections": [
{
"type": "introduction",
"contentMarkdown": "Most small business owners don't have a marketing department. AI content marketing tools promise to fill that gap, but the real question isn't whether AI can write — it's whether it can write like *you*."
},
{
"type": "body",
"heading": "Why small businesses are turning to AI content marketing",
"contentMarkdown": "Small business SEO used to mean choosing between hiring a writer or falling behind. AI content marketing changes that math by making a consistent publishing schedule achievable without a full-time hire."
},
{
"type": "body",
"heading": "Where AI helps most, and where it doesn't",
"contentMarkdown": "AI is strongest at first drafts, outlines, and repetitive formats like FAQs. It's weakest at judgment calls that depend on knowing your actual customers — so keep a human review step for anything customer-facing."
},
{
"type": "callout",
"contentMarkdown": "A five-minute voice check before publishing catches most AI-sounding phrasing.",
"callout": {
"label": "Quick tip",
"text": "Read the draft aloud. If it doesn't sound like something you'd actually say to a customer, rewrite that line."
}
},
{
"type": "body",
"heading": "Keeping your brand voice consistent",
"contentMarkdown": "Give the tool a short brand voice brief once, then reuse it: three adjectives, one thing you never say, and one real customer question you hear often."
},
{
"type": "body",
"heading": "A simple weekly workflow",
"contentMarkdown": "Draft on Monday, review and edit Tuesday, publish Wednesday. Keeping a fixed cadence matters more than any individual post."
},
{
"type": "faq",
"heading": "Frequently asked questions",
"contentMarkdown": ""
},
{
"type": "conclusion",
"contentMarkdown": "AI content marketing works best as a drafting partner, not a replacement for judgment. Start with one post a week and keep your own voice in the final pass."
}
],
"faqs": [
{
"question": "Will AI-written content hurt my SEO?",
"answer": "Search engines rank content on quality and usefulness, not on how it was drafted. Editing for accuracy and voice before publishing is what matters."
},
{
"question": "How much editing does an AI draft usually need?",
"answer": "Expect to adjust specific claims, add real examples from your business, and tighten anything that reads generic."
}
],
"conclusion": "AI content marketing works best as a drafting partner, not a replacement for judgment. Start with one post a week and keep your own voice in the final pass.",
"coverageNotes": {
"keywordCoverage": [
{
"keyword": "ai content marketing",
"covered": true,
"evidence": "Appears in title, H1, and introduction."
},
{
"keyword": "small business seo",
"covered": true,
"evidence": "Appears in the second H2 section."
}
]
}
}