Lexigen

API reference

POST /v1/generate

Generates one SEO-formatted blog post synchronously and returns it in the response body, with its quality report.

POST/api/v1/generate

Headers

  • AuthorizationBearer <API_KEY> (or X-API-Key: <API_KEY>)required
  • Content-Typeapplication/jsonrequired
  • Idempotency-Key<any string>
  • X-Request-ID<your id> (used as requestId; one is generated if omitted)

Scope

The key needs the generate scope. Keys created in the dashboard have it by default.

Request body fields

FieldTypeNotes
keywordsstring[]Required. 1–20 non-empty keywords. The first keyword is the primary keyword phrase the gates measure.
topicstring?Optional framing beyond the raw keywords, 1–200 characters.
languagestringRequired, 2–10 characters, e.g. "en".
regionstring?Up to 10 characters, e.g. "US".
tone"professional" | "friendly" | "bold"Required.
targetAudiencestring?Up to 200 characters.
brandVoicestring?Up to 200 characters.
industrystring?Up to 100 characters.
targetUrlstring?A URL, up to 2,048 characters: the page your article is about, such as a brand’s site. When set, it is read on every request (nothing is cached) to build a verified fact sheet. Only that hostname is read, and every specific claim must trace to a fact quoted from it. Without it, the article stays general: specific numbers, prices, plans and policies are removed. It is never linked in the published content.
factualityMode"standard" | "verified"Optional, defaults to "standard". "verified" fails with CONTENT_QUALITY_FAILED instead of returning an article when nothing could be verified. See the content quality pipeline.
constraintsobjectRequired. May be empty: {}.
constraints.maxWords / minWordsnumber?Accepted for compatibility (maxWords 100–8,000, minWords at least 50 and not above maxWords), but length is not targeted or enforced. Articles come back at their natural length. There is no per-request word cap.
constraints.maxSectionsnumber?1–20. Extra sections beyond this are dropped from the returned post.
constraints.includeFAQsboolean?Asks for a FAQ block. faqs may still be absent from the post.
constraints.includeInternalLinksPlaceholdersboolean?Asks for plain-text markers like [INTERNAL LINK: anchor text] where an internal link would fit.
constraints.keywordUsageStrategy"balanced" | "natural"Optional guidance for how keywords are worked in.
format.responseTypesArray<"json"|"markdown"|"html">Required, at least one. Controls which of rendered.rawJson, rendered.markdown and rendered.html are included. post is always returned.
idempotencyKeystring?Up to 255 characters. Same as the Idempotency-Key header (the header wins if both are sent).
clientProvidedRequestIdstring?Up to 255 characters. Accepted for your own bookkeeping; not echoed in the response.

The body must be valid JSON, at most 256 KB. Anything that fails these rules returns 400 VALIDATION_ERROR with the failing paths in details.issues.

Writing from your page

Send targetUrl to have specifics (prices, plans, policies, features) written from that page. Facts used, with their verbatim quotes, are listed in quality.qa.facts.

request body with targetUrl
{
  "keywords": [
    "example widgets review"
  ],
  "language": "en",
  "tone": "professional",
  "targetUrl": "https://www.example.com/widgets",
  "constraints": {},
  "format": {
    "responseTypes": [
      "html"
    ]
  }
}

Content quality

Every article is written facts-first and then checked by the universal quality gates: claims against the fact sheet (contradicted and unsupported claims are removed), hedge words, keyword and brand density, brand casing, boilerplate openers, sourced figures and recycled titles. Failures get up to 2 automatic repair passes. The best article is always returned with HTTP 200. If a gate still fails, quality.status is "fail" and quality.qa.failingGates lists what failed, so you decide whether to publish. Topics that depend on current information (prices, releases, regulations, statistics, news and similar) are written from recent, validated news coverage instead. Details are in the content quality pipeline.

Timing

A request with a targetUrl typically takes 60–110 seconds. Requests are allowed up to 300 seconds. If you can’t hold a connection that long, use POST /v1/jobs.

Status codes

  • 200: article returned (check quality).
  • 400 VALIDATION_ERROR: invalid body, or an idempotency key reused with a different body.
  • 401 AUTH_MISSING / AUTH_INVALID; 403 SCOPE_INSUFFICIENT.
  • 422 PROHIBITED_INPUT, CONTENT_QUALITY_FAILED (verified mode only) or SOURCE_VALIDATION_FAILED (no usable current sources, so no article).
  • 429 RATE_LIMITED or QUOTA_EXCEEDED.
  • 500 INTERNAL_ERROR: retry later. Use a new idempotency key, because a failed outcome is stored under the old one.

See error codes for bodies and handling.

Rate-limit headers

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds) for your key’s per-day window. When the per-minute window is the one that blocks, they describe it instead, and the 429 adds Retry-After. Every request that passes authentication and the monthly quota check counts toward these windows, even one that later fails validation or generation. Only successful generations count toward your monthly quota. See plans & limits.

Idempotency

Pass a key in the Idempotency-Key header or the body’s idempotencyKey field. Repeating the same key with the same body returns the stored outcome with its original status, including a stored failure, so generation only runs once and a retry after a dropped connection can’t double-count. While the original request is still running, a repeat returns 202 with {"status":"processing"}. Reusing a key with a different body returns VALIDATION_ERROR. Keys are scoped to your API key.

Response schema

  • requestId: also returned in the X-Request-ID header. Quote it in support requests.
  • post: the SEOPostV1 article (see the SEO formatting guide).
  • rendered: markdown, html and/or rawJson, per format.responseTypes.
  • quality: status ("pass" | "fail"), score, revisionCount (repair passes used, 0–2), qualityVersion and qa, which holds every gate with its value and threshold, every claim (removed ones marked omitted), the fixes applied, and qa.facts.facts[] (the facts used, each with its verbatim quote and source URL). Fact URLs are audit metadata only. Published content never contains a link.

curl example

shell
curl -X POST https://lexigen.app/api/v1/generate \
  -H "Authorization: Bearer $KEYWORD_TO_BLOG_API_KEY" \
  -H "Idempotency-Key: 3f7c2e9a-1d4b-4e2a-9c3d-8b1a2f4e5c6d" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
  "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"
}'

Example response — 200 OK

json
{
  "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
      }
    }
  }
}