Create Post

Endpoint

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

Request Body

Field	Type	Required	Description
`content`	string	Yes	The text body of your post
`publishNow`	boolean	Yes*	Set to `true` to publish immediately
`scheduledFor`	string	No	ISO 8601 datetime for scheduled posts
`timezone`	string	No	IANA timezone (default: `"UTC"`)

*Required when scheduledFor is not provided.

`platforms` (required)

An array of platform targets (min 1).

Field	Type	Required	Description
`platform`	string	Yes	`"twitter"`, `"instagram"`, `"youtube"`, `"tiktok"`, `"pinterest"`, `"linkedin"`, or `"reddit"`
`accountId`	string	Yes	Integration ID from `/v1/connect/integrations`
`content`	string	No	Per-platform text override. When set, this replaces the top-level `content` for this platform only. Useful when different platforms call for different copy (e.g. hashtags on Instagram, shorter on Twitter).
`platformSpecificData`	object	No	Platform-specific options (see Platforms)

`mediaItems` (optional)

An array of media attachments.

Field	Type	Required	Description
`type`	string	Yes	`"image"`, `"video"`, or `"gif"`
`url`	string	Yes	Public URL to the media file
`thumbnail`	string	No	Thumbnail URL (YouTube only)

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: Cross-Post to Multiple Platforms

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", "privacyStatus": "public" } }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://example.com/video.mp4" }
    ],
    "publishNow": true
  }'

Example: Per-Platform Content Override

Each platform entry accepts its own content field. When provided, it replaces the top-level content for that platform only — handy when you want a punchy tweet but a longer caption on Instagram.

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Shipped: faster scheduling, fewer clicks. 🚀",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "tw_123"
      },
      {
        "platform": "linkedin",
        "accountId": "li_789",
        "content": "Excited to share that we just shipped a major update to our scheduling engine. The team focused on two things: cutting time-to-publish and reducing the number of clicks it takes to get a post live across multiple channels. If you manage social for a brand or team, I would love your feedback."
      }
    ],
    "publishNow": true
  }'

Twitter falls back to the top-level content, while LinkedIn gets its own longer, more professional version.

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"
		}
	]
}

Status Codes

Code	Meaning
`202`	Post accepted — published, scheduled, partial, or failed
`400`	Validation error (bad request body)
`402`	Not enough credits
`403`	Forbidden
`503`	Scheduling unavailable

Partial Failures

When posting to multiple platforms, some may succeed and others fail. A 202 response with "status": "partial" 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.

On this page