PostMantis
API ReferencePosts

List posts

Returns posts visible to the authenticated caller, with optional filtering by status, profile, provider, and scheduled date range. Supports paginated iteration.

GET
/api/v1/posts

Returns posts visible to the authenticated caller, with optional filtering by status, profile, provider, and scheduled date range. Supports paginated iteration.

Authorization

BearerAuth
AuthorizationBearer <token>

PostMantis API key from the dashboard. Include as Authorization: Bearer <key>.

In: header

Query Parameters

status?string

Filter by post status: pending, scheduled, settled, or canceled.

Value in

  • "pending"
  • "settled"
  • "canceled"
  • "scheduled"
profileIds?array<>

Comma-separated list of profile UUIDs to filter by.

providers?array<>

Comma-separated list of provider names to filter by (e.g. x,linkedin).

scheduledAfter?string

Only posts scheduled at or after this ISO-8601 time.

Formatdate-time
scheduledBefore?string

Only posts scheduled at or before this ISO-8601 time.

Formatdate-time
page?|

Zero-based page index.

Range0 <= value
Default0
perPage?integer

Page size, 1-100. Default 20.

Range1 <= value <= 100
Default20

Response Body

application/json

application/problem+json

application/problem+json

curl -X GET "https://example.com/api/v1/posts"
{  "data": [    {      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",      "body": "Ship small. Learn fast.",      "status": "settled",      "createdAt": "2026-05-05T10:00:00.000Z",      "updatedAt": "2026-05-05T10:00:00.000Z",      "media": [],      "deliveries": [        {          "profileId": "4339a6bc-9cd3-455e-8f91-df8bc63f12d7",          "provider": "x",          "profileName": "PostMantis on X",          "status": "published",          "publishedAt": "2026-05-05T10:01:00.000Z",          "providerPostId": "1234567890",          "url": "https://x.com/postmantis/status/1234567890",          "providerOptions": {}        }      ]    }  ],  "pagination": {    "page": 0,    "perPage": 20,    "total": 1  }}

Disconnect a profile POST

Permanently disconnects a social profile. Existing scheduled posts targeting this profile will fail at delivery time. Requires write permission.

Create a post POST

Creates a publish-now post when `post.scheduledAt` is omitted, or a scheduled post when `post.scheduledAt` is a future ISO-8601 datetime. Accepts JSON or multipart/form-data (for direct file uploads). Posts must have a body, media, or both. Use `/uploads` first if you want server-verified artifacts.