---
title: "Generate one SEO article"
method: POST
path: "/v1/projects/{projectId}/articles"
tags: ["Articles"]
---

# Generate one SEO article

`POST /v1/projects/{projectId}/articles`

## Request

- Base URL: `https://serp-agent.com`
- URL: `https://serp-agent.com/v1/projects/{projectId}/articles`
- Auth: HTTP bearer

Enqueues end-to-end generation of ONE article for a topic and/or primary keyword (at least one required; the other is derived). Returns 202 with an `article_id` to poll at GET /v1/articles/{article_id}. The article is research-grounded, QA-checked, and returned as draft markdown — it is NEVER auto-published (fetch the content and publish it yourself). Only one API article may generate per project at a time (409 `article_in_progress`). Sandbox trial: 2 articles per key, watermarked as draft-only. Non-sandbox projects: included with an active subscription; without one, LIVE keys pay per unit from the prepaid credit balance (article_generated = 15 credits — 402 `insufficient_credits` when the balance is short; credit-funded articles stay draft-only). Typical completion: 10–30 minutes; poll every 60s.

## Path parameters

- `projectId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object: At least one of topic / primary_keyword is required.
  - `topic` string: Working title / topic. Placed verbatim as the article's planned title.
  - `primary_keyword` string: Target keyword. Derived from topic (lowercased) when omitted.

## Response `202`

Article generation queued. Poll the `poll` path.

- ArticleAccepted
  - `article_id` string, required
  - `status` 'queued', required
  - `poll` string, required: Path to poll: GET /v1/articles/{article_id}.

## Other responses

- `400`: Malformed body, or neither topic nor primary_keyword given. Code: `invalid_request`.
- `401`: Missing, malformed, unknown, revoked, or expired API key. Codes: `unauthorized`, `key_revoked`, `key_expired`.
- `402`: Payment needed. `payment_required` (sandbox key, no subscription) or `insufficient_credits` (live key, no subscription, balance below 15 credits — body carries `required_credits`, `balance_credits`, `purchase`, `subscription_alternative`).
- `403`: Sandbox article budget exhausted (2 per trial). Code: `sandbox_limit_reached`.
- `404`: No such project on this account. Code: `not_found`.
- `409`: An article is already generating for this project. Code: `article_in_progress`.
- `429`: Rate limit exceeded (600 requests/minute per API key). Honor `Retry-After`.

---

[API](https://skmtc.dev/serp-agent/apis/serp-agent-api.md) · [All operations](https://skmtc.dev/serp-agent/apis/serp-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/serp-agent/apis/serp-agent-api/revisions/438a943019ac?raw)