Publishing API

Ampost's Publishing API sends one post to every account you choose, across eleven social networks, in a single request. Each REST operation has a matching MCP tool, so an AI agent can do the same through Ampost's MCP server.

Every endpoint, field and error code is in the full API reference; to connect an AI agent, see Set up the MCP server.

Publish to several networks in one request

Send POST /api/posts with your API key as a Bearer token. targets lists the platforms, here Instagram and LinkedIn in one platform set (omit platformSetId for your default set). text and media go to every platform, and publishNow publishes the post in the same call. Ampost answers 201 with the post.

terminal
curl -X POST https://api.ampost.io/api/posts \
  -H "Authorization: Bearer amp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "targets": [
    {
      "platformSetId": "0b6e4d2a-9c3f-4e1b-8a7d-5f2c1e9b3d40",
      "platforms": [
        "instagram",
        "linkedin"
      ]
    }
  ],
  "text": "Launch day: Ampost publishes everywhere from one API.",
  "firstComment": "Pricing and docs: https://ampost.io",
  "media": [
    {
      "url": "https://cdn.example.com/launch.mp4",
      "type": "video",
      "mimeType": "video/mp4",
      "sizeBytes": 18200000,
      "width": 1080,
      "height": 1920,
      "durationSeconds": 21
    }
  ],
  "options": {
    "instagram": {
      "placement": "reel"
    },
    "linkedin": {
      "text": "Launch day. Here is what we built and why.",
      "visibility": "PUBLIC"
    }
  },
  "publishNow": true,
  "metadata": {
    "campaignId": "launch-2026"
  }
}'

Each item in media is a public https URL with a required type (image or video). To upload files instead, see Media upload.

Schedule instead of publishing now

Set scheduledFor instead of publishNow and Ampost publishes the post at that time. Without either, the new post is a draft.

terminal
curl -X POST https://api.ampost.io/api/posts \
  -H "Authorization: Bearer amp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "targets": [
    {
      "platforms": [
        "facebook",
        "threads"
      ]
    }
  ],
  "text": "Webinar starts in one hour.",
  "linkUrl": "https://example.com/webinar",
  "scheduledFor": "2027-01-14T15:00:00Z"
}'

To publish a draft or scheduled post now, call POST /api/posts/:postId/publish:

terminal
curl -X POST https://api.ampost.io/api/posts/$POST_ID/publish \
  -H "Authorization: Bearer amp_live_YOUR_KEY"

The response

The reference's example 201 response to the request above:

Response
{
  "id": "7f1c2a9e-4b1d-4c55-9a0e-2f6d8b3c1a10",
  "status": "published",
  "targets": [
    {
      "platformSetId": "0b6e4d2a-9c3f-4e1b-8a7d-5f2c1e9b3d40",
      "platforms": [
        "instagram",
        "linkedin"
      ]
    }
  ],
  "platforms": [
    "instagram",
    "linkedin"
  ],
  "text": "Launch day: Ampost publishes everywhere from one API.",
  "firstComment": "Pricing and docs: https://ampost.io",
  "linkUrl": null,
  "media": [
    {
      "url": "https://cdn.example.com/launch.mp4",
      "type": "video",
      "mimeType": "video/mp4",
      "sizeBytes": 18200000,
      "width": 1080,
      "height": 1920,
      "durationSeconds": 21,
      "altText": null,
      "thumbnailUrl": null
    }
  ],
  "mediaFit": "pad",
  "thread": [],
  "options": {
    "instagram": {
      "placement": "reel"
    },
    "linkedin": {
      "text": "Launch day. Here is what we built and why.",
      "visibility": "PUBLIC"
    }
  },
  "scheduledFor": null,
  "queuePlatformSetId": null,
  "source": "api",
  "metadata": {
    "campaignId": "launch-2026"
  },
  "platformPosts": [
    {
      "platform": "instagram",
      "accountId": "c41d8e2f-6a3b-4f9c-b1e5-7d2a9c4e6f80",
      "platformSetId": "0b6e4d2a-9c3f-4e1b-8a7d-5f2c1e9b3d40",
      "status": "published",
      "platformPostId": "17895695668004550",
      "publishedUrl": "https://www.instagram.com/reel/C9xYz12AbCd/",
      "text": null,
      "error": null,
      "notice": null,
      "warnings": [],
      "attempts": 1,
      "nextAttemptAt": null,
      "firstComment": {
        "status": "published",
        "commentId": "17858893269123456",
        "error": null,
        "reason": null,
        "updatedAt": "2026-10-06T09:00:04.000Z"
      },
      "mediaTransforms": null,
      "thread": null,
      "createdAt": "2026-10-06T09:00:00.000Z",
      "updatedAt": "2026-10-06T09:00:04.000Z"
    },
    {
      "platform": "linkedin",
      "accountId": "5e9a1c3d-7b2f-4d8e-a6c1-3f9b2e7d4a60",
      "platformSetId": "0b6e4d2a-9c3f-4e1b-8a7d-5f2c1e9b3d40",
      "status": "published",
      "platformPostId": "urn:li:share:7248123456789012345",
      "publishedUrl": "https://www.linkedin.com/feed/update/urn:li:share:7248123456789012345/",
      "text": null,
      "error": null,
      "notice": null,
      "warnings": [],
      "attempts": 1,
      "nextAttemptAt": null,
      "firstComment": {
        "status": "failed",
        "commentId": null,
        "error": {
          "code": "PLATFORM_ERROR",
          "message": "LinkedIn comment failed: the service is temporarily unavailable",
          "retryable": true,
          "platformCode": null,
          "platformSubcode": null
        },
        "reason": null,
        "updatedAt": "2026-10-06T09:00:04.000Z"
      },
      "mediaTransforms": null,
      "thread": null,
      "createdAt": "2026-10-06T09:00:00.000Z",
      "updatedAt": "2026-10-06T09:00:04.000Z"
    }
  ],
  "createdAt": "2026-10-06T09:00:00.000Z",
  "updatedAt": "2026-10-06T09:00:04.000Z"
}
  • id: The post's id, for /api/posts/:postId calls.
  • status: The post's overall status, such as draft, scheduled, posting, published, partial or failed.
  • targets: The platform sets and platforms the post goes to, as in the request.
  • platforms: Every platform the post goes to, once each.
  • text: The text sent to every platform that has no options.<platform>.text.
  • firstComment: The comment posted on each new post right after it publishes, or null.
  • linkUrl: The link the post shares, or null.
  • media: The media as you sent it; what Ampost converted for a platform is in platformPosts[].mediaTransforms.
  • mediaFit: How media outside a platform's aspect ratio is fitted: pad (default), crop or none.
  • thread: Follow-up posts on X, Bluesky and Threads, each a reply to the one before; empty when there is none.
  • options: The per-platform settings and overrides from the request.
  • scheduledFor: When the post publishes, or null for a draft or a post published right away.
  • queuePlatformSetId: The platform set whose queue slot the post holds (useQueue), or null.
  • source: Where the post was created: api, mcp or dashboard.
  • metadata: Your own object from the request, unchanged; webhook post events carry it too.
  • platformPosts: One result per account, with its platform, set, status, published URL, error and notice.
  • createdAt: When the post was created.
  • updatedAt: When the post last changed.

Check each network's result

Read platformPosts for each account's result: its status, publishedUrl and error. An account with a video may stay processing while the platform processes it; Ampost checks until it is published or failed. A post whose accounts partly failed is partial; retry the failed ones with POST /api/posts/:postId/retry.

GET /api/posts/:postId returns one post with its platformPosts. To find posts in a given state, GET /api/posts takes a status filter:

terminal
curl -X GET https://api.ampost.io/api/posts?status=partial \
  -H "Authorization: Bearer amp_live_YOUR_KEY"

To be told instead of polling, add a webhook.

Per-network options

options.<platform> changes the post for one platform: every platform accepts its own text, and some add settings of their own, such as placement on Instagram and Facebook or visibility on LinkedIn, as in the example above. Unknown keys are rejected; the schema per platform is in GET /api/platforms. What each network supports is on its page: Instagram API, Facebook API, LinkedIn API, TikTok API, Threads API, X API, YouTube API, Pinterest API, Bluesky API, Telegram API, Discord API.

Supported networks

The value in platforms is shown next to each name.

  • Instagram instagram
  • Facebook facebook
  • LinkedIn linkedin
  • TikTok tiktok
  • Threads threads
  • X twitter
  • Discord discord
  • Telegram telegram
  • Bluesky bluesky
  • YouTube youtube
  • Pinterest pinterest

Do it from an AI agent

The MCP tool posts_create takes the same fields as POST /api/posts, so an agent connected to Ampost's MCP server can create, schedule or publish the same post. Connect your client with Set up the MCP server, or follow the Cursor guide.