Reference
JSON schemas
Example bodies for every request and response shape of the Keyword-to-Blog API, labelled with their versioned type names. Field names match the wire format exactly. Optional fields that are absent are simply omitted. Field-by-field rules are on each endpoint page.
POST /v1/generate — request
GenerateRequestV1
{
"keywords": [
"ai content marketing",
"small business seo"
],
"topic": "How small businesses can use AI content marketing without losing their voice",
"language": "en",
"region": "US",
"tone": "friendly",
"targetAudience": "small business owners with no in-house marketing team",
"brandVoice": "warm, practical, no jargon",
"industry": "marketing services",
"constraints": {
"maxSections": 6,
"includeFAQs": true,
"keywordUsageStrategy": "natural"
},
"format": {
"responseTypes": [
"json",
"markdown"
]
},
"clientProvidedRequestId": "req_local_0192"
}POST /v1/jobs — request
JobsCreateRequestV1
{
"generateRequest": {
"keywords": [
"ai content marketing",
"small business seo"
],
"topic": "How small businesses can use AI content marketing without losing their voice",
"language": "en",
"region": "US",
"tone": "friendly",
"targetAudience": "small business owners with no in-house marketing team",
"brandVoice": "warm, practical, no jargon",
"industry": "marketing services",
"constraints": {
"maxSections": 6,
"includeFAQs": true,
"keywordUsageStrategy": "natural"
},
"format": {
"responseTypes": [
"json",
"markdown"
]
},
"clientProvidedRequestId": "req_local_0192"
},
"webhook": {
"url": "https://example.com/webhooks/lexigen",
"events": [
"job.succeeded",
"job.failed"
]
},
"format": {
"responseTypes": [
"json",
"markdown"
]
},
"idempotencyKey": "job_create_local_0192"
}Generated post — response
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."
}
]
}
}GET /v1/jobs/{jobId} — response
JobV1
{
"jobId": "job_5f2a9d3e1b",
"status": "succeeded",
"createdAt": "2026-09-10T14:02:11.000Z",
"updatedAt": "2026-09-10T14:03:38.000Z",
"requestId": "req_9f3a1c2e4b",
"inputSummary": {
"keywords": [
"ai content marketing",
"small business seo"
],
"language": "en"
},
"result": {
"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."
}
]
}
},
"rendered": {
"markdown": "# AI Content Marketing for Small Businesses: A Practical Starting Point\n\nMost small business owners don't have a marketing department..."
},
"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
}
}
}
}GET /v1/usage — response
UsageResponseV1
{
"plan": {
"id": "growth",
"name": "Growth",
"priorityProcessing": false,
"teamSeats": 3
},
"periodStart": "2026-09-01T00:00:00.000Z",
"periodEnd": "2026-10-01T00:00:00.000Z",
"metering": {
"unit": "word",
"granularity": "generation"
},
"limits": {
"monthlyWords": 200000,
"monthlyPosts": 5000,
"maxWordsPerRequest": 2000,
"requestsPerMinute": 15
},
"consumed": {
"words": 42300,
"posts": 51,
"requests": 51
},
"remaining": {
"words": 157700,
"posts": 4949,
"requests": 4949
},
"daily": {
"limit": 500,
"used": 12,
"remaining": 488,
"resetAt": "2026-09-15T00:00:00.000Z"
}
}Webhook payloads
WebhookSucceededPayloadV1
{
"event": "job.succeeded",
"jobId": "job_5f2a9d3e1b",
"requestId": "req_9f3a1c2e4b",
"post": {
"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."
}
]
}
},
"rendered": {
"markdown": "# AI Content Marketing for Small Businesses: A Practical Starting Point\n\nMost small business owners don't have a marketing department..."
},
"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
}
}
}
}Error schema
Every non-2xx response uses this shape. See error codes for the full list.
ErrorResponseV1
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body.",
"requestId": "req_99887766bb",
"details": {
"issues": [
{
"path": [
"tone"
],
"message": "Invalid option: expected one of \"professional\"|\"friendly\"|\"bold\""
}
]
}
}
}