PostMantis
API ReferencePosts

Create a 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`.

POST
/api/posts

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.

Authorization

BearerAuth
AuthorizationBearer <token>

API key from the PostMantis dashboard.

In: header

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

post*
profiles*array<>
Items1 <= items
media?array<|>
Items1 <= items <= 20
provider_options?

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/json

application/problem+json

curl -X POST "https://postmantis.com/api/posts" \  -H "Content-Type: application/json" \  -d '{    "post": {      "body": "Draft copy for approval.",      "draft": true    },    "profiles": [      "4339a6bc-9cd3-455e-8f91-df8bc63f12d7"    ]  }'

{  "data": {    "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      }    ]  }}

{  "type": "https://postmantis.com/problems/invalid-request",  "title": "Invalid request",  "status": 400,  "detail": "The request payload failed validation.",  "code": "invalid_request"}
{  "type": "https://postmantis.com/problems/unauthorized",  "title": "Unauthorized",  "status": 401,  "detail": "Missing or invalid API key.",  "code": "unauthorized"}
{  "type": "https://postmantis.com/problems/forbidden",  "title": "Forbidden",  "status": 403,  "detail": "The authenticated API key is not allowed to perform this action.",  "code": "forbidden"}
{  "type": "https://postmantis.com/problems/post-media-not-supported",  "title": "Post media not supported",  "status": 409,  "detail": "Current publishing flow supports at most one media item per post.",  "code": "post_media_not_supported"}
{  "type": "https://postmantis.com/problems/payload-too-large",  "title": "Payload too large",  "status": 413,  "detail": "Remote media exceeds the 256 MB limit.",  "code": "payload_too_large"}
{  "type": "https://postmantis.com/problems/unsupported-media-type",  "title": "Unsupported media type",  "status": 415,  "detail": "Unsupported content type. Use application/json or multipart/form-data.",  "code": "unsupported_media_type"}
{  "type": "https://postmantis.com/problems/upload-not-ready",  "title": "Upload not ready",  "status": 422,  "detail": "Referenced upload must be completed before it can be attached to a post.",  "code": "upload_not_ready"}
{  "error": "Too Many Requests"}
{  "type": "https://postmantis.com/problems/service-unavailable",  "title": "Service unavailable",  "status": 503,  "detail": "Publishing is temporarily unavailable. Try again later.",  "code": "service_unavailable"}

List posts GET

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 a post GET

Returns one post with media and per-delivery details when the full post is visible to the authenticated API key.