PostMantis
API ReferencePosts

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

POST
/api/v1/posts

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.

Authorization

BearerAuth
AuthorizationBearer <token>

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

In: header

Request Body

Post creation payload

TypeScript Definitions

Use the request body type in TypeScript.

post*

Post content and optional schedule.

profiles*array<>

Target profile UUIDs from GET /api/v1/profiles. At least one. Duplicates are rejected.

Items1 <= items
media?array<>

Media attachments referencing verified artifact ids. 1-20 items. Required if body is omitted.

Items1 <= items <= 20
providerOptions?

Per-provider overrides (e.g. board id for Pinterest). Keys must match selected providers.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/api/v1/posts" \  -H "Content-Type: application/json" \  -d '{    "post": {      "body": "Ship small. Learn fast."    },    "profiles": [      "4339a6bc-9cd3-455e-8f91-df8bc63f12d7"    ]  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "status": "pending",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "media": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "artifactId": "706a3f1e-c357-4634-b1bf-20c221b5bb4e",        "artifactStatus": "reserved",        "contentType": "string",        "url": "http://example.com",        "alt": "string"      }    ],    "deliveries": [      {        "provider": "x",        "profileName": "string",        "status": "pending",        "providerOptions": {          "property1": null,          "property2": null        },        "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",        "scheduledAt": "2019-08-24T14:15:22Z",        "publishedAt": "2019-08-24T14:15:22Z",        "failedAt": "2019-08-24T14:15:22Z",        "providerPostId": "string",        "url": "http://example.com",        "errorMessage": "string"      }    ],    "body": "string",    "scheduledAt": "2019-08-24T14:15:22Z",    "canceledAt": "2019-08-24T14:15:22Z"  }}

List posts GET

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

Get a single post GET

Returns full post state including media processing status and per-provider delivery outcomes. Omitted fields mean no value. Use this to poll delivery status after creation.