API Reference / Posts

List posts

PostPiper API: page through owned posts by status, platform, account, or time range. Supports cursor pagination, filters, and sort options.

GEThttps://api.postpiper.ai/v1/posts

Posts are newest first. With status=scheduled, the soonest scheduled post appears first.

Time ranges require time_field and ISO 8601 timestamps with time zones. from is inclusive; to is exclusive.

For the next page, send next_cursor with the same filters and sort options.

Path and query parameters

Name	Type	Description
status	string, optional	draft, scheduled, published, or failed. Omit for all statuses.
platform	string, optional	Lowercase platform identifier, such as x or linkedin.
account_id	UUID, optional	Filter to one owned account.
time_field	string, optional	created_at, scheduled_at, or published_at; required with from or to.
from	ISO 8601 string, optional	Inclusive start time with a time zone.
to	ISO 8601 string, optional	Exclusive end time with a time zone.
sort_by	string, optional	created_at (default), scheduled_at (default for scheduled status), or published_at. Posts without that timestamp are excluded.
sort_order	string, optional	desc for creation and publication time; asc for scheduled time, unless specified.
limit	integer, optional	Page size from 1 to 100; defaults to 50.
cursor	string, optional	Opaque next_cursor from a previous response.

Example request

Terminal

curl -H "Authorization: Bearer $POSTPIPER_API_KEY" "https://api.postpiper.ai/v1/posts"

Response

200 OK. Returns posts and a nullable next_cursor.

JSON

{
  "posts": [
    {
      "id": "<post-uuid>",
      "content": "A scheduled post",
      "media_urls": [],
      "asset_ids": [],
      "platform": "x",
      "status": "scheduled",
      "account_id": "<account-uuid>",
      "created_at": "2030-10-12T01:00:00.000Z",
      "scheduled_at": "2030-10-13T01:00:00.000Z",
      "published_at": null,
      "platform_post_id": null,
      "platform_post_url": null
    }
  ],
  "next_cursor": null
}

Errors

400INVALID_CURSOR for a malformed or mismatched cursor; INVALID_TIME_RANGE for invalid time filters.
401Missing or invalid API key.
403API key lacks the required scope.