docs(sdk): document the GET /api/posts ordering change

The webapp now orders posts by COALESCE(published_at, scheduled_at, created_at)
DESC, id DESC rather than created_at alone -- a post drafted weeks before it
published was sorting by when it was written, burying it in its own Published
listing.

No field changed, but the ordering is observable behaviour that consumers page
through, so it is stated at every surface: spec, public spec copy, Postman,
node + python list methods, and the list_posts MCP tool description.

node 1.8.0 -> 1.8.1, python 0.9.0 -> 0.9.1, mcp-server 1.12.1 -> 1.12.2.

Author: Azym

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026-08-01 — `GET /api/posts` ordering (node SDK 1.8.1, python SDK 0.9.1, MCP 1.12.2)
+
+### Changed
+
+- **`GET /api/posts` is ordered by the timestamp that applies to each post**, newest first: `publishedAt` if the post is live, else `scheduledAt` if it is due, else `createdAt`, with `id` descending as a tiebreaker. It previously ordered by `createdAt` alone, so a post drafted weeks before it published sorted among the day it was *written* rather than the day it went live — on a real account a post published today sat 92 rows down its own Published listing. Drafts and scheduled posts are unaffected in practice, since their applicable timestamp is the one they were already sorted by. Documented in the spec, the Postman collection, both SDK list methods, and the `list_posts` MCP tool. No request or response field changed.
+
 ## 2026-08-01 — tool descriptions no longer steer the host model (MCP 1.12.1)
 
 Raised by the Anthropic MCP Directory review.

mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bulkpublish/mcp-server",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "description": "Model Context Protocol server for BulkPublish — lets AI assistants manage social media posts, channels, media, and analytics.",
   "mcpName": "io.github.azeemkafridi/bulkpublish",
   "repository": {

mcp-server/src/index.ts

@@ -755,7 +755,7 @@ server.tool(
 
 server.tool(
   "list_posts",
-  "List posts with optional filters for status, search text, date range, channel, and label. Returns paginated results with platform statuses and metrics.",
+  "List posts with optional filters for status, search text, date range, channel, and label. Returns paginated results with platform statuses and metrics, ordered newest-first by publishedAt if the post is live, else scheduledAt, else createdAt.",
   {
     status: z
       .enum(["draft", "scheduled", "publishing", "published", "processing", "failed", "partial"])

node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulkpublish",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Social media automation API for AI agents, LLMs, and developers. Publish to 11 platforms programmatically.",
   "author": "BulkPublish",
   "license": "MIT",

node/src/posts.ts

@@ -43,6 +43,11 @@ export class PostsResource {
   /**
    * List posts with pagination and filters.
    *
+   * Ordered newest-first by the timestamp that applies to each post:
+   * `publishedAt` if it is live, else `scheduledAt` if it is due, else
+   * `createdAt`. A post drafted weeks before it publishes sorts by when it went
+   * live, not when it was written.
+   *
    * @param params - Filtering and pagination options.
    * @returns Paginated list of posts with relations.
    *

openapi.json

@@ -840,7 +840,7 @@
           "Posts"
         ],
         "summary": "List posts",
-        "description": "Retrieve posts with pagination, filtering, and search.",
+        "description": "Retrieve posts with pagination, filtering, and search. Results are ordered newest-first by the timestamp that applies to each post — publishedAt if it is live, else scheduledAt if it is due, else createdAt — with id descending as a tiebreaker. A post written weeks before it publishes therefore sorts by when it went live, not when it was drafted.",
         "parameters": [
           {
             "name": "page",

postman-collection.json

@@ -10,7 +10,7 @@
           "request": {
             "name": "List posts",
             "description": {
-              "content": "Retrieve posts with pagination, filtering, and search.",
+              "content": "Retrieve posts with pagination, filtering, and search. Results are ordered newest-first by the timestamp that applies to each post — publishedAt if it is live, else scheduledAt if it is due, else createdAt — with id descending as a tiebreaker. A post written weeks before it publishes therefore sorts by when it went live, not when it was drafted.",
               "type": "text/plain"
             },
             "url": {

python/bulkpublish/posts.py

@@ -50,6 +50,11 @@ def list(
     ) -> PostList:
         """List posts with optional filtering and pagination.
 
+        Ordered newest-first by the timestamp that applies to each post:
+        ``published_at`` if it is live, else ``scheduled_at`` if it is due, else
+        ``created_at``. A post drafted weeks before it publishes sorts by when it
+        went live, not when it was written.
+
         Args:
             status: Filter by status (``"draft"``, ``"scheduled"``,
                 ``"published"``, ``"failed"``).

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bulkpublish"
-version = "0.9.0"
+version = "0.9.1"
 description = "Social media automation API for AI agents, LLMs, and developers. Publish to 11 platforms programmatically."
 readme = "README.md"
 license = "MIT"