API

Blog Admin API

Platform admin endpoints for the Rankion blog: posts, categories, author management.

The blog admin API drives the Rankion-owned marketing blog at rankion.ai/blog — not your project articles. It is exclusively accessible to platform admins (internal editorial, marketing team); regular team tokens get 403. If you are looking for the content API: that is the Articles API.

Module context: Blog (Admin).

Method	Endpoint	Description
GET	`/v1/blog/categories`	All categories (sorted by `position`)
POST	`/v1/blog/categories`	New category. Body: `{name, slug?, parent_id?, color?}`
PUT	`/v1/blog/categories/{id}`	Update
DELETE	`/v1/blog/categories/{id}`	Delete — returns `409` if posts are still assigned

Posts

A post corresponds to one publicly indexable blog article at rankion.ai/blog/{slug}.

Method	Endpoint	Description
GET	`/v1/blog/posts`	List, paginated. Filters: `?status=draft\|published\|archived`, `?category=`, `?author=`, `?q=`
POST	`/v1/blog/posts`	New post (see body below)
GET	`/v1/blog/posts/{id}`	Detail including SEO fields, author, categories
PUT	`/v1/blog/posts/{id}`	Update
DELETE	`/v1/blog/posts/{id}`	Soft-delete

Create a post

curl -X POST "$BASE/blog/posts" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "title": "How GEO Scoring Works in 2026",
    "slug": "how-geo-scoring-works-2026",
    "content": "<p>Markdown or HTML…</p>",
    "excerpt": "GEO is more than a buzzword — here is how Rankion measures AI visibility…",
    "status": "draft",
    "category_ids": [3, 7],
    "author_id": 12,
    "featured_image_url": "https://cdn.rankion.ai/blog/geo-2026.png",
    "meta_title": "GEO Scoring 2026 — Rankion",
    "meta_description": "How we measure AI visibility, what sets GEO apart from SEO, …",
    "scheduled_publish_at": "2026-05-15T09:00:00Z"
  }'

Response 201:

{
  "data": {
    "id": 188,
    "slug": "how-geo-scoring-works-2026",
    "status": "draft",
    "public_url": "https://rankion.ai/blog/how-geo-scoring-works-2026",
    "created_at": "2026-05-01T10:14:00Z"
  }
}

Status lifecycle

draft  ─►  scheduled  ─►  published  ─►  archived
                                    │
                                    └─►  draft  (rollback via PUT)

scheduled_publish_at flips automatically to published on reach (cron-based, 1-min granularity).
archived is visible in the admin list, but 410 for public visitors.

Author management

Authors are Rankion users with is_blog_author=true. A dedicated author endpoint is not (as of 2026-05) publicly exposed — author assignment goes through author_id in the post body. Author master data (name, avatar, bio) lives in the user profile.

Notes

Platform-admin only. All endpoints check is_platform_admin on the token user. Regular team tokens (even team owners) get 403 Forbidden.
Slugs are globally unique, not per team — if your slug collides with an existing post, the API returns 422 with a suggested slug.
Soft-delete is reversible via PUT {status: "draft"} on the ID. The public slug stays blocked for 30 days so URLs are not immediately stolen by new posts.
Featured-image URL must be CDN-reachable — Rankion re-fetches the image on publish via og-image-cache to guarantee OG previews.
scheduled_publish_at is UTC. Convert local timezone explicitly, otherwise the post goes live too early/late.
No hard delete via API. Permanent removal only happens through the internal admin panel — the DELETE route is always a soft-delete.

Related: Articles API · Blog (Admin).