Posts

Schedule post

Queues a draft post for publishing through Postiv's dispatcher. Never publishes immediately; if the profile has human approvers, the post waits for approval first.

POST/api/public/posts/:id/schedule

cURLPOST /api/public/posts/:id/schedule

curl -X POST https://postiv.ai/api/public/posts/ID_ID/schedule \
  -H "Authorization: Bearer pk_postiv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledTime": "2026-08-01T09:30:00.000Z",
    "integrationId": 123,
    "mediaType": "text"
  }'

200Response

{
  "success": true,
  "schedule": {
    "queueEntry": {
      "id": "q1...",
      "postId": "post1...",
      "integrationId": 1234,
      "scheduledTime": "2026-07-20T09:00:00.000Z",
      "status": "queued",
      "mediaType": "text"
    },
    "requiresApproval": false,
    "approverCount": 0,
    "autoApproved": false,
    "remainingApprovers": 0,
    "message": "Post scheduled successfully"
  }
}

Authorization

Requires an organization API key with the posts:schedule scope, sent as Authorization: Bearer or x-api-key.

Path parameters

idstringrequired

Resource id from the corresponding list or create endpoint.

Body parameters

scheduledTimestringrequired

ISO-8601 timestamp, must be >= 2 minutes in the future.

integrationIdintrequired

Alias: integration_id. Target profile; for plan-linked posts must equal that plan's profile.

mediaTypestring

Alias: media_type. Omit to auto-detect (uses the post's attached image if any).

One of:textimagecarousel

mediaUrlsstring|string[]

Alias: media_urls. Max 20 URLs, each a valid URL.

carouselIduuid

Alias: carousel_id. Required if mediaType='carousel' or to publish an infographic (auto-detected format). Carousels need a rendered PDF first; infographics render automatically at schedule time.

mediaDataobject

Alias: media_data. { title?, altText?, description?, commentPlug? }.

commentPlugobject

Alias: comment_plug. { mode: inherit|disable|override, text?, imageSource?, delayMinutes? (min 15) }. Merged into mediaData.commentPlug if not already set there.

Response

The scheduling result.

schedule.queueEntryobject

{ id, postId, integrationId, scheduledTime, status, mediaType }

schedule.requiresApprovalboolean

schedule.approverCountint

schedule.autoApprovedboolean

true if the scheduler is themself an approver and auto-approved their own post.

schedule.remainingApproversint

schedule.messagestring

Human-readable status message.

Errors

400	unsupported_media_type / missing_carousel_id / scheduled_time_in_past / invalid_integration_id / invalid_scheduled_time / empty_post_content / missing_post_text
400	linkedin_cmm_reconnect_required: a Comment Plug is in play but the profile's LinkedIn comment permission isn't connected
404	post_not_found / linkedin_profile_not_found
400	post_already_published: post status is already published
409	post_already_scheduled: a live queue entry already exists (duplicate-call guard)
409	carousel_already_scheduled: the carousel is already scheduled on a different post
409	carousel_pdf_not_ready: carousel media type requested but no rendered PDF; call render-carousel first
502	infographic_render_failed: automatic canvas render failed at schedule time

Good to know

If mediaType/mediaUrls are both omitted, an image already attached to the post via generate_post_image/edit_post_image is auto-attached. carouselId + no explicit mediaType auto-detects carousel vs. infographic format from the carousel's saved content and adjusts mediaType/mediaUrls accordingly (infographics publish as an image post of the rendered canvas PNG).