PostMantis
API ReferencePosts

List posts

Returns a paginated list of posts visible to the authenticated API key. Post visibility is all-or-nothing: a post appears only when all deliveries on that post are inside the key scope. Use the `deliveries` array for per-destination results. For `profile_ids` and `providers`, generated clients should send repeated query keys; the server also accepts comma-separated values for compatibility.

GET
/api/posts

Returns a paginated list of posts visible to the authenticated API key. Post visibility is all-or-nothing: a post appears only when all deliveries on that post are inside the key scope. Use the deliveries array for per-destination results. For profile_ids and providers, generated clients should send repeated query keys; the server also accepts comma-separated values for compatibility.

Authorization

BearerAuth
AuthorizationBearer <token>

API key from the PostMantis dashboard.

In: header

Query Parameters

status?string

Filter posts by workflow status.

Value in"draft" | "pending" | "scheduled" | "completed" | "canceled"
profile_ids?array<>

Filter by profile id. Send repeated keys such as ?profile_ids=id1&profile_ids=id2. The server also accepts comma-separated values for compatibility.

providers?array<>

Filter by provider. Send repeated keys such as ?providers=x&providers=youtube. The server also accepts comma-separated values for compatibility.

scheduled_after?string

Filter to posts scheduled at or after this ISO 8601 timestamp.

Formatdate-time
scheduled_before?string

Filter to posts scheduled at or before this ISO 8601 timestamp.

Formatdate-time
page?|

Zero-based page number.

Default0
Range0 <= value
per_page?integer

Number of posts to return per page. Maximum 100.

Default20
Range1 <= value <= 100

Response Body

application/json

application/problem+json

application/json

curl -X GET "https://postmantis.com/api/posts"
{  "data": [    {      "id": "74d6f3d9-6b68-4a2d-9d89-c4510a08ff42",      "body": "Big announcement tomorrow.",      "status": "scheduled",      "draft": false,      "scheduled_at": "2026-03-30T10:00:00Z",      "created_at": "2026-03-29T09:30:00Z",      "updated_at": "2026-03-29T09:30:00Z",      "canceled_at": null,      "media": [        {          "id": "f4a457b3-99ad-47d7-beb8-a64d8efdc6ef",          "status": "processed",          "content_type": null,          "url": null,          "asset_id": "8f5f3f18-3cf7-4aa8-a0ea-6fd204d4c4f1",          "alt": "Launch card",          "error_message": null        }      ],      "deliveries": [        {          "profile_id": "4339a6bc-9cd3-455e-8f91-df8bc63f12d7",          "provider": "x",          "profile_name": "Julius",          "status": "pending",          "scheduled_at": "2026-03-30T10:00:00Z",          "published_at": null,          "failed_at": null,          "provider_post_id": null,          "url": null,          "error_message": null        },        {          "profile_id": "8d3ef50f-98d9-4a44-8cf7-0b7fb53ab0a8",          "provider": "instagram",          "profile_name": "Brand",          "status": "pending",          "scheduled_at": "2026-03-30T10:00:00Z",          "published_at": null,          "failed_at": null,          "provider_post_id": null,          "url": null,          "error_message": null        }      ]    },    {      "id": "1d2aafec-bf13-4ea4-b271-6f9ac1e9d069",      "body": "Draft copy for approval.",      "status": "draft",      "draft": true,      "scheduled_at": null,      "created_at": "2026-03-29T09:30:00Z",      "updated_at": "2026-03-29T09:30:00Z",      "canceled_at": null,      "media": [],      "deliveries": [        {          "profile_id": "4339a6bc-9cd3-455e-8f91-df8bc63f12d7",          "provider": "x",          "profile_name": "Julius",          "status": "pending",          "scheduled_at": null,          "published_at": null,          "failed_at": null,          "provider_post_id": null,          "url": null,          "error_message": null        }      ]    },    {      "id": "57f383c7-36fb-4d53-a7b4-64f59c2f72bc",      "body": "The launch is live.",      "status": "completed",      "draft": false,      "scheduled_at": "2026-03-29T09:45:00Z",      "created_at": "2026-03-29T09:30:00Z",      "updated_at": "2026-03-29T09:46:10Z",      "canceled_at": null,      "media": [        {          "id": "f4a457b3-99ad-47d7-beb8-a64d8efdc6ef",          "status": "processed",          "content_type": null,          "url": null,          "asset_id": "8f5f3f18-3cf7-4aa8-a0ea-6fd204d4c4f1",          "alt": "Launch card",          "error_message": null        }      ],      "deliveries": [        {          "profile_id": "4339a6bc-9cd3-455e-8f91-df8bc63f12d7",          "provider": "x",          "profile_name": "Julius",          "status": "published",          "scheduled_at": "2026-03-29T09:45:00Z",          "published_at": "2026-03-29T09:45:21Z",          "failed_at": null,          "provider_post_id": "xt_193204923",          "url": "https://x.com/julius/status/193204923",          "error_message": null        },        {          "profile_id": "9aa032e9-bf7d-4355-b4c1-96f191c2f7ee",          "provider": "youtube",          "profile_name": "Launch Channel",          "status": "failed",          "scheduled_at": "2026-03-29T09:45:00Z",          "published_at": null,          "failed_at": "2026-03-29T09:46:10Z",          "provider_post_id": null,          "url": null,          "error_message": "Upload expired before YouTube fetched the file."        }      ]    }  ],  "pagination": {    "page": 0,    "per_page": 20,    "total": 3  }}
{  "type": "https://postmantis.com/problems/unauthorized",  "title": "Unauthorized",  "status": 401,  "detail": "Missing or invalid API key.",  "code": "unauthorized"}
{  "error": "Too Many Requests"}

Overview

The mental model for profiles, posts, media, and the current public PostMantis API contract.

Create a post POST

Creates a draft, scheduled post, or immediate publish request. Non-draft writes are accepted in `pending` first and then advanced asynchronously by the publishing workflow. The request must include `post.body`, `media`, or both. Draft requests must not include `post.scheduled_at`.