Skip to main content
Posts

List Posts

Retrieve a paginated list of posts with filtering and sorting.

Endpoint

GET https://api.postpeer.dev/v1/posts

Query Parameters

ParameterTypeDefaultDescription
statusstring—Filter by status: "draft", "scheduled", "published", "failed", or "partial"
platformstring[]—Filter by platform (repeatable, OR logic). e.g. ?platform=twitter&platform=instagram
createdAfterstring—ISO 8601 lower bound on createdAt
createdBeforestring—ISO 8601 upper bound on createdAt
scheduledAfterstring—ISO 8601 lower bound on scheduledFor
scheduledBeforestring—ISO 8601 upper bound on scheduledFor
limitinteger20Page size (1–100)
offsetinteger0Number of posts to skip
sortstring"desc"Sort by createdAt: "asc" or "desc"

Example

curl "https://api.postpeer.dev/v1/posts?status=published&platform=twitter&limit=5" \
  -H "x-access-key: YOUR_API_KEY"

Response

{
  "success": true,
  "total": 42,
  "posts": [
    {
      "postId": "post_abc123",
      "content": "Hello world!",
      "status": "published",
      "scheduledFor": null,
      "timezone": "UTC",
      "mediaItems": [],
      "platforms": [
        {
          "platform": "twitter",
          "status": "published",
          "platformPostId": "1234567890",
          "platformPostUrl": "https://twitter.com/you/status/1234567890",
          "publishedAt": "2026-04-15T14:30:00.000Z",
          "errorMessage": null
        }
      ],
      "crosspostingEnabled": false,
      "createdAt": "2026-04-15T14:30:00.000Z",
      "updatedAt": "2026-04-15T14:30:01.000Z"
    }
  ]
}

Status Codes

CodeMeaning
200Success
400Invalid query parameters

Create Post

Publish content to one or more social platforms with a single API call.

Get Post

Retrieve a single post by its ID.

On this page

Endpoint
Query Parameters
Example
Response
Status Codes