Skip to content
PostMCP/ai

create_post

Creates a post and either queues it for a future slot or broadcasts it immediately. Targeting is the important decision here — targetAccounts names exact profiles, platforms fans out to every profile connected on that network. Every targeted profile is stored as its own post with its own id, so each can be edited, retried or cancelled on its own. Attach one file with mediaUrl, or several with mediaUrls to publish a carousel.

Access
write
Category
Publishing
Endpoint
POST/api/tools/create_post
On this page
  1. Parameters
  2. Example request
  3. Response

Parameters

content
stringrequired
Text body of the post. Used for any profile that does not carry copy of its own.
targetAccounts
array<object>preferred
The exact profiles that should receive the post. Only these profiles are published to, and each becomes a separate post.
platform
enumrequired
linkedin · twitter · facebook · instagram · threads · bluesky · youtube
profileId
string
Id returned by get_connected_accounts.
username
string
Handle, carried through for readability.
userId
string
Platform-side user id, when the network needs it.
content
string
Copy for this profile only, overriding the shared content.
mediaUrl
string
Media for this profile only, overriding the shared mediaUrl / mediaUrls.
mediaUrls
array<string>
A carousel for this profile only, replacing the shared set — the way to give X or Bluesky a four-slide cut of a longer Instagram carousel.
youtube
object
Upload details for this profile only, when it is a YouTube channel. Same shape as the top-level youtube object.
youtube
object
What a YouTube upload is sent with. Ignored for other platforms. The Short is uploaded with privacyStatus as its visibility, applied to that new upload only — nothing already on the channel is changed. Confirm the visibility with the user before creating the post.
title
string
Video title, up to 100 characters. Defaults to the first line of the copy.
description
string
Video description, up to 5000 characters. Defaults to the whole copy.
privacyStatus
enum
public · unlisted · privatedefault: public
variants
object
Per-platform copy keyed by platform name, or by "platform:profileId" for a single profile. e.g. { "twitter": "short version", "linkedin": "longer version" }.
platforms
array<enum>
Whole networks to publish to. Every connected profile on each network listed here receives the post.
publishImmediately
boolean
Broadcast right now instead of queueing.default: false
scheduleDate
string
YYYY-MM-DD. Required when publishImmediately is false.
scheduleTime
string
HH:MM, 24-hour. Required when publishImmediately is false.
timezone
string
IANA zone the schedule above is written in, e.g. Asia/Kolkata. Pass the user’s own zone whenever wall-clock time matters.default: UTC
mediaUrl
string
Public URL of one image or video to attach. For several files, use mediaUrls.
mediaUrls
array<string>
Every image/video to attach, in the order they should appear. One URL is an ordinary media post; two or more publish as a carousel (Instagram 2–10, Threads 2–20), a multi-photo post (Facebook up to 10, LinkedIn up to 20) or a gallery (X and Bluesky up to 4). Only Instagram and Threads mix video into a set of several. Wins over mediaUrl when both are given.
workspaceId
string
Workspace to act on, from list_workspaces. Omit to use the default workspace on the key.

Example request

curl -X POST "https://api.postmcpai.com/api/tools/create_post" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $POSTMCPAI_API_KEY" \
  -d '{
    "content": "Shipping the PostMCP AI integration for Claude Desktop and Cursor today. 🚀",
    "targetAccounts": [
      {
        "platform": "linkedin",
        "profileId": "lin_7741903"
      },
      {
        "platform": "twitter",
        "profileId": "tw_1293847",
        "content": "PostMCP AI now plugs straight into Claude Desktop and Cursor. Ship posts from your editor. 🚀"
      }
    ],
    "publishImmediately": false,
    "scheduleDate": "2026-08-02",
    "scheduleTime": "10:00",
    "timezone": "Asia/Kolkata",
    "mediaUrl": "https://postmcpai.com/assets/banner.png"
  }'

Response

One post per targeted profile, each with the id you will need for update_post, publish_post_now, and delete_post. posts[0] is repeated as post for callers written against the older single-post response.

200 · application/json
{
  "success": true,
  "message": "2 posts created successfully, one per profile",
  "postIds": [
    "66a50c89e4b019a2b72f",
    "66a50c89e4b019a2b730"
  ],
  "posts": [
    {
      "id": "66a50c89e4b019a2b72f",
      "content": "Shipping the PostMCP AI integration for Claude Desktop and Cursor today. 🚀",
      "targets": [
        {
          "platform": "linkedin",
          "profileId": "lin_7741903",
          "status": "pending"
        }
      ],
      "status": "scheduled",
      "scheduleDate": "2026-08-02",
      "scheduleTime": "10:00",
      "timezone": "Asia/Kolkata"
    },
    {
      "id": "66a50c89e4b019a2b730",
      "content": "PostMCP AI now plugs straight into Claude Desktop and Cursor. Ship posts from your editor. 🚀",
      "targets": [
        {
          "platform": "twitter",
          "profileId": "tw_1293847",
          "status": "pending"
        }
      ],
      "status": "scheduled",
      "scheduleDate": "2026-08-02",
      "scheduleTime": "10:00",
      "timezone": "Asia/Kolkata"
    }
  ]
}