PostMantis - Agent-ready social publishing infrastructure

Practical request examples for drafts, scheduling, uploads, and multi-provider publishing.

Naming reminder

profiles = selected publishable destinations — provider_options = provider-specific request options — read responses later to inspect delivery outcomes.

Draft first

Drafts are created with post.draft: true. They still require profiles and cannot include scheduled_at.

{
  "post": {
    "body": "Draft copy for review.",
    "draft": true
  },
  "profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7"]
}

Create and publish now

{
  "post": {
    "body": "The launch is live."
  },
  "profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7", "8d3ef50f-98d9-4a44-8cf7-0b7fb53ab0a8"]
}

Immediate publish is still asynchronous. The accepted state is pending, and a very fast response may already serialize as scheduled.

Create and schedule for later

{
  "post": {
    "body": "Big announcement tomorrow.",
    "scheduled_at": "2026-03-30T10:00:00Z"
  },
  "profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7", "8d3ef50f-98d9-4a44-8cf7-0b7fb53ab0a8"]
}

Publish an existing draft now

curl https://postmantis.com/api/posts/74d6f3d9-6b68-4a2d-9d89-c4510a08ff42/publish \
  -X POST \
  -H "Authorization: Bearer $POSTMANTIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Publish an existing draft later

curl https://postmantis.com/api/posts/74d6f3d9-6b68-4a2d-9d89-c4510a08ff42/publish \
  -X POST \
  -H "Authorization: Bearer $POSTMANTIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-03-30T12:00:00Z"
  }'

Cancel a scheduled post

curl https://postmantis.com/api/posts/74d6f3d9-6b68-4a2d-9d89-c4510a08ff42/cancel \
  -X POST \
  -H "Authorization: Bearer $POSTMANTIS_API_KEY"

Cancellation only works after the post reached scheduled and while every delivery is still pending.

Delete a draft

curl https://postmantis.com/api/posts/74d6f3d9-6b68-4a2d-9d89-c4510a08ff42 \
  -X DELETE \
  -H "Authorization: Bearer $POSTMANTIS_API_KEY"

Use delete only for posts still in draft status. Use cancel for scheduled posts you want to stop while keeping the record and its delivery history.

Media

Reference a publicly accessible file by URL. PostMantis imports it during request ingestion, stores it as an owned asset, and then publishes from owned media.

{
  "post": { "body": "Launch image" },
  "profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7"],
  "media": [
    {
      "url": "https://assets.example.com/launch-card.png",
      "alt": "Launch card"
    }
  ]
}

Complete an upload session first, then reference its asset_id. Use this for private, local, or large files.

{
  "post": { "body": "Upload-first flow" },
  "profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7"],
  "media": [
    {
      "asset_id": "8f5f3f18-3cf7-4aa8-a0ea-6fd204d4c4f1",
      "alt": "Launch card"
    }
  ]
}

See Uploads for the two-step create → complete asset flow.

Use multipart when the file lives on disk and you want to create the post in one call.

curl https://postmantis.com/api/posts \
  -X POST \
  -H "Authorization: Bearer $POSTMANTIS_API_KEY" \
  -F 'post[body]=Launch image' \
  -F 'profiles[]=4339a6bc-9cd3-455e-8f91-df8bc63f12d7' \
  -F 'media[0][file]=@./launch-card.png' \
  -F 'media[0][alt]=Launch card'

Field pattern: media[n][file|url|asset_id|alt]. For each media[n], send exactly one of file, url, or asset_id.

Provider-specific parameters

profiles selects destinations. provider_options carries provider-specific behavior for those destinations.

{
  "post": { "body": "Launch video" },
  "profiles": ["9aa032e9-bf7d-4355-b4c1-96f191c2f7ee", "4339a6bc-9cd3-455e-8f91-df8bc63f12d7"],
  "media": [
    {
      "asset_id": "8f5f3f18-3cf7-4aa8-a0ea-6fd204d4c4f1",
      "alt": "Launch video"
    }
  ],
  "provider_options": {
    "youtube": {
      "title": "Launch video",
      "privacy_status": "public"
    },
    "tiktok": {
      "format": "video",
      "privacy_status": "PUBLIC_TO_EVERYONE"
    }
  }
}

Not supported in the current public write contract

Thread replies are not part of the current post write shape. Create one post per request, then read the post later to inspect deliveries[].

Examples