Publishing

Publish a Post

Send a POST request to create and publish content immediately or schedule it for later.

POST https://api.postpeer.dev/v1/posts

Request Body

Field	Type	Required	Description
`content`	string	Yes	The text body of your post
`platforms`	array	Yes	List of platforms to post to (min 1)
`platforms[].platform`	string	Yes	`"twitter"`, `"instagram"`, or `"youtube"`
`platforms[].accountId`	string	Yes	Integration ID from `/v1/connect/integrations`
`platforms[].platformSpecificData`	object	No	Platform-specific options (see Platforms)
`mediaItems`	array	No	Media attachments
`mediaItems[].type`	string	Yes	`"image"`, `"video"`, or `"gif"`
`mediaItems[].url`	string	Yes	Public URL to the media file
`mediaItems[].thumbnail`	string	No	Thumbnail URL (YouTube only)
`publishNow`	boolean	Yes*	Set to `true` to publish immediately
`scheduledAt`	string	No	ISO 8601 datetime for scheduled posts
`timezone`	string	No	IANA timezone (default: `"UTC"`)

*Required when scheduledAt is not provided.

Example: Publish Now

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Launching our new feature today!",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" },
      { "platform": "instagram", "accountId": "def456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://example.com/image.png" }
    ],
    "publishNow": true
  }'

Example: Publish to Multiple Platforms

Post the same content to Twitter, Instagram, and YouTube simultaneously:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out our latest video!",
    "platforms": [
      { "platform": "twitter", "accountId": "tw_123" },
      { "platform": "youtube", "accountId": "yt_456", "platformSpecificData": { "title": "Our Latest Video", "visibility": "public" } }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://example.com/video.mp4" }
    ],
    "publishNow": true
  }'

Response

{
  "success": true,
  "status": "published",
  "postId": "post_abc123",
  "platforms": [
    {
      "platform": "twitter",
      "success": true,
      "platformPostUrl": "https://twitter.com/you/status/123456"
    },
    {
      "platform": "instagram",
      "success": true,
      "platformPostUrl": "https://instagram.com/p/abc123"
    }
  ]
}

Response Status Codes

Code	Meaning
`200`	All platforms published successfully
`201`	Post scheduled for later
`207`	Partial success — some platforms failed
`400`	Validation error (bad request body)
`402`	Not enough credits
`502`	All platforms failed
`503`	Scheduling unavailable

Partial Failures

When posting to multiple platforms, some may succeed and others fail. A 207 response includes per-platform results:

{
  "success": true,
  "status": "partial",
  "postId": "post_abc123",
  "platforms": [
    { "platform": "twitter", "success": true, "platformPostUrl": "..." },
    { "platform": "instagram", "success": false, "error": "Image URL is not publicly accessible" }
  ]
}

Failed platform posts don't consume credits.