Sign in

v5

OpenAPI 3.0.02026-08-034760291.5 KB
Generate Article

Generate a full article from a brief (one-shot)

Create and generate a complete SnowSEO article in one call (the automated, one-shot flow). Provide only the high-level brief — the type-specific outline, target keywords, and FAQ prompts are all produced for you (so coverage is populated), and you never have to write or pass them yourself. Every article must belong to a topic cluster: pass a topicId from topic_clusters_list (or create one with create_topic_cluster); the topic name comes from that cluster. Ask the user for the length tier (it sets the credit cost). CONSUMES CREDITS: always ask the user for permission before calling this. It returns right away with { slug, generating, status } while the article is written in the background; poll generation_status with that slug until it is no longer generating, then read the article with get_article. For step-by-step control instead, use the wizard (create_article → generate_titles/generate_outline/generate_keywords/generate_prompts → start_article_generation). Set startGeneration:false to create only the draft (and call start_article_generation later).

post/v3/generate-article/create-and-start/

Request body

teamIdstring

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

titlestring required

Article title / headline.

type'listicle' | 'guide' | 'comparison' | 'review' | 'news'

Article type. Defaults to listicle.

contentArticleType'pillar' | 'cluster'

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

primaryKeywordsstring[]

Primary target keywords.

secondaryKeywordsstring[]

Secondary keywords.

promptInsightsstring[]

Questions / search intents the article should answer.

topicIdstring 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.

competitorUrlsstring[]

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

length'short' | 'medium' | 'long' required

Required length tier — short: 800–1000 words (~100 credits), medium: 1800–2000 words (~200 credits), long: 2800–3000 words (~300 credits). Ask the user which tier they want before calling, since it sets the credit cost.

tonestring

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

customInstructionsstring

Optional free-text writing instructions for THIS article only (focus, angle, things to include or avoid). Ask the user if they have any; if omitted, the brand's default content guidelines still apply automatically.

customInstructionsUseWithBrandboolean

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.

internalLinkTargetSlugsstring[]

Slugs of existing SnowSEO articles to link out to.

internalLinkTargetUrlsstring[]

Absolute http(s) URLs to link out to.

includeTldrboolean

Include a TL;DR section. Defaults to true.

includeFaqboolean

Include an FAQ section. Defaults to true.

includeConclusionboolean

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

includeCtaboolean

Include a CTA section. Defaults to false.

startGenerationboolean

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

Response

Default Response