---
title: "Generate a full article from a brief (one-shot)"
method: POST
path: "/v3/generate-article/create-and-start/"
tags: ["Generate Article"]
---

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

`POST /v3/generate-article/create-and-start/`

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

## Request body

- object
  - `teamId` string — Team id (falls back to the session's active project).
  - `title` string, required — Article title / headline.
  - `type` 'listicle' | 'comparison' | 'news' | 'review' | 'guide' — Article type. Defaults to listicle.
  - `contentArticleType` 'pillar' | 'cluster' — Pillar or cluster role in a topic cluster. Omit for a standalone post.
  - `primaryKeywords` string[] — Primary target keywords.
  - `secondaryKeywords` string[] — Secondary keywords.
  - `promptInsights` string[] — Questions / search intents the article should answer.
  - `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.
  - `competitorUrls` string[] — 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.
  - `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). Ask the user if they have any; if omitted, the brand's default content guidelines still apply automatically.
  - `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.
  - `internalLinkTargetSlugs` string[] — Slugs of existing SnowSEO articles to link out to.
  - `internalLinkTargetUrls` string[] — 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`

Default Response

---

[API](https://skmtc.net/snowseo/apis/snowseo-api.md) · [All operations](https://skmtc.net/snowseo/apis/snowseo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/snowseo/snowseo-api/versions/8f92b00b75d6/schema)