Skip to main content
POST
Start article generation
Start generating content for an existing draft (created by Create Article). Body: slug (required), teamId, customInstructions (saved on the article; send an empty string to clear), customInstructionsUseWithBrand, and targetWordCount (300-10000, only used when the draft has no outline yet). Returns { success: true, generating: true, slug, requiredCredits } when a run starts. If a run is already in progress it returns { success: true, generating: true, slug, alreadyRunning: true } instead, with no requiredCredits. 404 if the slug is not found for the team. Limited to 100 requests per day.
This uses AI credits. The cost depends on the article’s target length (chosen when the draft/outline was created): roughly 100 credits for ~800-1000 words, 200 for ~1800-2000, or 300 for ~2800-3000. If your balance is too low the call returns 402 with code INSUFFICIENT_CREDITS, generating: false and requiredCredits, and nothing starts.
Generation runs in the background - poll Generation Status below until it finishes. Check error before reading the article with Get Article. Calling Start Generation again while a run is already in progress is safe and will not start a duplicate.

Generation Status

GET /v3/generate-article/generation-status?slug=<slug> Check whether an article is currently being generated or updated, and how far along it is. Pass the article’s slug as a query parameter. When generating is false, check error before reading the article; a successful new generation has status: "generated". The response includes slug, articleId, status, generating, kind (generate or update), phase, progress, enrichmentPhase (post-content JSON-LD and audit work that can continue after generating is false), and error. Returns 404 for an unknown slug.

Authorizations

Authorization
string
header
required

Your SnowSEO API key (sk_...).

Body

application/json
slug
string
required

Slug of the draft article to generate.

teamId
string

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

customInstructions
string

Optional free-text writing instructions for this article, layered on top of the team's default content guidelines. Persists onto the article for future regenerations. Omit to leave the stored value unchanged; send an empty string to clear it.

customInstructionsUseWithBrand
boolean

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

targetWordCount
integer

Target article length in words. Only used when the draft has NO outline yet - the worker plans one and this sets its size (and the credit cost). Ignored when an outline already exists, since its own target wins. Defaults to 1900.

Required range: 300 <= x <= 10000

Response

Success: { success:true, generating:true, slug } (+ alreadyRunning:true when a run was already in flight).

Success: { success:true, generating:true, slug } (+ alreadyRunning:true when a run was already in flight).

success
boolean
generating
boolean
slug
string
requiredCredits
number
message
string
alreadyRunning
boolean