Skip to main content
POST
Generate a full article from a brief (one-shot)
Generate a full article end-to-end from a short brief. SnowSEO builds the structured outline, target keywords, and FAQ prompts for you, creates the draft, and writes the content in the background.
This uses AI credits. The article is written asynchronously - the call returns a slug immediately. Poll Generation Status with that slug. Once generating is false, check error and status before reading the article with Get Article.

How it works

  1. Provide a title, a topicId (the topic cluster the article belongs to), a length tier, and optionally a tone or customInstructions.
  2. The outline, target keywords, and FAQ prompts are generated for you - you don’t need to provide or author them. You can still seed primaryKeywords (one entry; extras are stored as secondary), secondaryKeywords, promptInsights, competitorUrls (up to 5), internalLinkTargetSlugs, and internalLinkTargetUrls.
  3. A draft is created and generation starts. The response is { slug, articleId, generating, started, status } (plus requiredCredits / message / alreadyRunning when relevant). It is sent as a keep-alive stream (application/x-ndjson): leading whitespace is a heartbeat, and the final line is the JSON result. An error after streaming starts arrives as a { success: false, error, code } line with HTTP 200. When credits run short the draft is still created and the final line has started: false with code INSUFFICIENT_CREDITS. A missing or invalid topicId returns 400 before the stream opens.
  4. Poll the status with that slug; when generation finishes without an error, fetch the article.

Notes

  • Topic is required. Every article belongs to a topic cluster. Pass a topicId from Topics, or create one with Create Topic. The topic name is taken from the cluster.
  • Length sets the cost. length is required: short (800-1000 words, ~100 credits), medium (1800-2000, ~200), or long (2800-3000, ~300). If your credit balance can’t cover it, the draft is still created but generation does not start, and the response carries requiredCredits and a message.
  • Type (type) is listicle (default), comparison, news, review, or guide. Other optional fields: contentArticleType (pillar or cluster), tone, and includeTldr, includeFaq, includeConclusion, includeCta (default to your brand settings). Limited to 20 requests per minute.
  • Custom instructions (customInstructions) are optional, per-article writing guidance. Your brand’s default content guidelines (Brand Settings → About) are always applied automatically.
  • Language is optional. Omit it and the article uses your brand’s Writing Language (Settings → Content & CMS → Articles), falling back to your brand’s default language. Pass a language code such as es to write this one article in a different language. Codes are usually two letters, with three exceptions: Chinese is zh_CN or zh_TW, and Hebrew is iw (the legacy code, not he). Whichever applies is recorded on the article, so later refreshes, audits, and editor commands stay in that language even if the brand setting changes.
  • Set startGeneration: false to create the draft only, then call Start Generation later.

Prefer step-by-step?

Use the wizard tools for granular control: Generate Titles → Generate Outline → Create Article → Start Generation.

Authorizations

Authorization
string
header
required

Your SnowSEO API key (sk_...).

Body

application/json
title
string
required

Article title / headline.

topicId
string
required

Required. Id of the team's topic cluster this article belongs to - get it from topic_clusters_list, or create one with create_topic_cluster. The topic name is taken from this cluster; do not pass a free-text topic.

length
enum<string>
required

Required length tier - short: 800–1000 words (~100 credits), medium: 1800–2000 words (~200 credits), long: 2800–3000 words (~300 credits). The tier sets the credit cost.

Available options:
short,
medium,
long
teamId
string

Team id (falls back to the session's active project).

type
enum<string>

Article type. Defaults to listicle.

Available options:
listicle,
comparison,
news,
review,
guide
contentArticleType
enum<string>

Pillar or cluster role in a topic cluster. Omit for a standalone post.

Available options:
pillar,
cluster
primaryKeywords
string[]

The one search term the article targets. Pass a single entry; extra entries are stored as secondary keywords.

secondaryKeywords
string[]

Secondary keywords.

promptInsights
string[]

Questions / search intents the article should answer.

competitorUrls
string[]

Up to 5 competitor article URLs to inform the outline's competitive analysis.

tone
string

Writing tone (e.g. 'Professional', 'Casual'). Defaults to professional.

customInstructions
string

Optional free-text writing instructions for THIS article only (focus, angle, things to include or avoid). The brand's default content guidelines apply either way.

customInstructionsUseWithBrand
boolean

When true (default), the article's custom instructions apply together with the brand's content guidelines. When false, they replace the brand guidelines for this article.

Slugs of existing SnowSEO articles to link out to.

Absolute http(s) URLs to link out to.

includeTldr
boolean

Include a TL;DR section. Defaults to true.

includeFaq
boolean

Include an FAQ section. Defaults to true.

includeConclusion
boolean

Include a conclusion (ignored for listicles). Defaults to true.

includeCta
boolean

Include a CTA section. Defaults to false.

startGeneration
boolean

Start content generation now (default true). False creates only the draft.

language
string

Language code to write this article in (e.g. 'es'). Usually two letters; Chinese is 'zh_CN'/'zh_TW' and Hebrew is 'iw'. Defaults to the brand's Writing Language, then its brand language. Only pass this when the user asks for a specific language for this one article.

Response

200 - application/x-ndjson

A newline-delimited stream. Whitespace keeps the connection alive; status and final result are JSON lines. An error after streaming starts is returned as a JSON error line with HTTP 200.

Newline-delimited JSON events