> ## Documentation Index
> Fetch the complete documentation index at: https://snowseo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Article
> Create a draft article from a pre-built outline.
Create a draft article. This does **not** generate body content — for a fully AI-written article in one step, use [Generate Article](/docs/api-reference/endpoints/generate-article).
Use this when you already have an outline from [Generate Outline](/docs/api-reference/endpoints/generate-outline) and want manual control. Pass the outline under `articleOutline`, then call [Start Generation](/docs/api-reference/endpoints/start-generation) with the returned `slug` to write the content.
A valid `topicId` is required — every article belongs to a topic cluster. Use [Topics](/docs/api-reference/endpoints/topics) to find one, or [Create Topic](/docs/api-reference/endpoints/create-topic) to add one. The topic name is taken from the cluster.
The optional `language` field sets the language code the article is written in (e.g. `es`). Codes are usually two letters, with three exceptions: Chinese is `zh_CN` or `zh_TW`, and Hebrew is `iw` (the legacy code, not `he`). Omit it to use your brand's Writing Language (Settings → Content & CMS → Articles), falling back to your brand's default language. Whichever applies is recorded on the article, so later refreshes, audits, and editor commands stay in that language even if the brand setting changes.
## OpenAPI
````yaml POST /v3/cms/articles
openapi: 3.0.0
info:
title: SnowSEO API
description: API documentation for SnowSEO
version: 1.0.0
servers:
- url: https://api.snowseo.com
description: Production server
security: []
tags:
- name: Keywords
description: Keyword research and suggestion end-points
- name: Onboarding
description: Brand onboarding and strategy end-points
- name: Brands
description: Brand management end-points
- name: Organizations
description: Organization and member end-points
- name: Integrations
description: Google Search Console and other integrations
- name: Utilities
description: Common utility end-points like screenshots and uploads
externalDocs:
url: https://snowseo.com/docs
description: Find more info here
paths:
/v3/cms/articles:
post:
tags:
- CMS
summary: Create an article (draft) from a pre-built outline
description: >-
Create a draft article. This does NOT generate the body content. For a
fully AI-written article, prefer `generate_article` (which produces the
outline and the content in one step). Use this only when you already
have an outline from `generate_outline` and want manual control: pass
that outline under `articleOutline` (see its description), then call
`start_article_generation` with the returned `slug` to write the
content.
operationId: createArticle
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- title
- topicId
properties:
teamId:
type: string
description: Team id (falls back to the session's active project).
title:
type: string
description: Article title.
content:
type: string
description: >-
Optional markdown body. Leave empty for a draft you will
fill via start_article_generation.
type:
type: string
default: blog
description: >-
Article type: listicle | guide | comparison | review | news
(or blog for a generic post). Must match the outline's
structure.
status:
type: string
default: draft
contentArticleType:
type: string
nullable: true
description: >-
"pillar" or "cluster" for pillar/cluster content,
null/omitted for generic posts.
authorName:
type: string
topicId:
type: string
description: >-
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).
keywords:
type: array
items:
type: object
properties:
keyword:
type: string
type:
type: string
enum:
- primary
- secondary
required:
- keyword
- type
prompts:
type: array
items:
type: object
properties:
prompt:
type: string
type:
type: string
enum:
- primary
- secondary
topic:
type: string
required:
- prompt
- type
metaData:
type: object
properties:
metaDescription:
type: string
metaTitle:
type: string
ogTitle:
type: string
ogDescription:
type: string
twitterTitle:
type: string
twitterDescription:
type: string
canonicalUrl:
type: string
articleOutline:
type: object
additionalProperties: true
description: >-
Outline wrapper consumed by the generator. Shape: {
generateOutlineResponse: , outlineAdditionalElements: {
targetWordCount:number, _shouldIncludeFAQ:boolean,
_shouldIncludeTldr:boolean,
_shouldIncludeConclusion:boolean, _shouldIncludeCTA:boolean
}, outlineNonEditable: { introduction: { estimated_words:150
}, conclusion?: { estimated_words:150 } },
audience_level:'auto', content_tone?:string }. Do NOT
hand-author the outline — obtain it from generate_outline
and pass it through unchanged.
internalLinkTargetSlugs:
type: array
items:
type: string
description: >-
Slugs of existing SnowSEO articles to link out to (internal
links).
internalLinkTargetUrls:
type: array
items:
type: string
description: >-
Absolute http(s) URLs to link out to that are not SnowSEO
articles.
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
article:
type: object
properties:
slug:
type: string
teamId:
type: string
title:
type: string
status:
type: string
type:
type: string
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
````