---
title: "Generate one SEO article from a topic (consumes 1 prepaid unit, $9 pay-as-you-go). Returns 202 + id; poll GET /articles/{id} until status=ready for markdown + html."
method: POST
path: "/articles"
---

# Generate one SEO article from a topic (consumes 1 prepaid unit, $9 pay-as-you-go). Returns 202 + id; poll GET /articles/{id} until status=ready for markdown + html.

`POST /articles`

## Request

- Base URL: `https://app.seomatic.ai/api/v1`
- URL: `https://app.seomatic.ai/api/v1/articles`
- Auth: HTTP bearer

## Request body

- object
  - `topic` string, required: The keyword/topic to write about, e.g. "how to choose trail running shoes".
  - `caller_ref` string: Optional opaque tag for YOUR end customer (e.g. "shop:1234"), stored on the article. For approved reseller accounts (contact support), the daily failed-article and cancel limits apply per tag under an account-wide ceiling, so one customer cannot lock out the others; on every other account the account-wide limits apply as without a tag. Never send secrets or personal data.

## Response `202`

{ id, status: "queued", poll } - generation runs async (typically a few minutes).

## Other responses

- `400`: topic missing (INVALID_REQUEST)
- `401`: Missing or invalid API key
- `402`: No prepaid articles remaining (ARTICLE_BALANCE_EMPTY). Body carries buy_url; POST /articles/checkout returns a payment link.
- `429`: Rate limited, or too many failed articles in 24 hours (ARTICLE_FAILURE_CAP; scope "caller" = this caller_ref only (reseller accounts), "org" = the whole account). Nothing was consumed.

---

[API](https://skmtc.dev/seomatic/apis/seomatic-api.md) · [All operations](https://skmtc.dev/seomatic/apis/seomatic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/seomatic/apis/seomatic-api/revisions/113a2a263604?raw)