Articles API

The articles API is the most-used part of the Rankion API — a single article typically goes through create → generate → score → optimize → publish, optionally plus repurpose, freshness check, and internal linking. All endpoints live under /v1/articles/... and are team-scoped.

Full module documentation: AI Content Editor · walkthrough with screenshots: Your First Article.

CRUD

Generation

curl -X POST "$BASE/articles/$ART/generate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "keyword": "AI coding tools",
    "article_type": "blog",
    "target_length": 1500,
    "tone": "expert",
    "language": "en",
    "style_profile_id": 3,
    "content_goal_id": 2
  }'

Response 202 Accepted:

{
  "article_id": 88,
  "status": "pending",
  "message": "Generation dispatched"
}

Then poll GET /v1/articles/{id} until processing_status == "ready". Standalone variant without a project: POST /v1/generate/article (same credits).

Scoring & optimization

The score response includes sub-scores (readability, keyword coverage, structural requirements, GEO signals), a list of concrete improvement suggestions, and an overall score 0–100.

Repurpose

Generates compact variants for social/newsletter from the original article.

Without format, all formats are generated (same price of 3 credits). With format, only the requested one.

# All formats
curl -X POST "$BASE/articles/$ART/repurpose" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{}'

# LinkedIn only
curl -X POST "$BASE/articles/$ART/repurpose" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"format":"linkedin"}'

Publish

Publishes the article through a configured CMS integration (WordPress, Shopify, custom REST adapter).

curl -X POST "$BASE/articles/$ART/publish" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cms_integration_id":1}'

Response 202 with job ID. Status afterwards via GET /v1/articles/{id} (cms_publish_status). A second publish call while a job is in flight → 409 Conflict (prevents duplicates).

Versions

Every generative step (generate, optimize, restore) creates an immutable version. This lets you roll back or compare.

Freshness

Detects outdated stats/year numbers/links and suggests updates — important for SEO stability on evergreen content.

Internal linking

Complete example: create → generate → score → publish

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"
PID=12   # existing project

# 1) Create stub
ART=$(curl -s -X POST "$BASE/projects/$PID/articles" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"AI Coding Tools 2026","status":"draft"}' \
  | jq -r .data.id)

# 2) Start generation (5 credits, async)
curl -s -X POST "$BASE/articles/$ART/generate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"keyword":"AI coding tools","article_type":"blog","target_length":1500,"language":"en"}'

# 3) Poll until ready
while [ "$(curl -s "$BASE/articles/$ART" \
  -H "Authorization: Bearer $TOKEN" | jq -r .data.processing_status)" != "ready" ]; do
  echo "Generating..."; sleep 5
done

# 4) Compute score
curl -s -X POST "$BASE/articles/$ART/score" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.scores'

# 5) Optional: repurpose for LinkedIn
curl -s -X POST "$BASE/articles/$ART/repurpose" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"format":"linkedin"}'

# 6) Publish via CMS integration ID 1
curl -s -X POST "$BASE/articles/$ART/publish" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cms_integration_id":1}'

# 7) Check publish status
curl -s "$BASE/articles/$ART" -H "Authorization: Bearer $TOKEN" \
  | jq '{cms_publish_status, public_url}'

Notes & pitfalls

• Generate is async. Even when the endpoint returns 200 — the content is only there once the job finishes. Always poll.
• Score needs content. POST /score without sufficient content returns a validation error instead of a useless 0 score.
• Publish is exclusive. While a publish job is running you cannot publish again — 409. Check status first.
• Versions are immutable. Restoring does not overwrite the old version, it creates a new version with the old content.

Related: Projects API · Credits · AI Content Editor · Your First Article.