API Reference / Posts

Create a draft

PostPiper API: create an unpublished post draft with text and/or images for X, LinkedIn, or Pinterest. Draft creation does not publish the post.

POSThttps://api.postpiper.ai/v1/posts

Provide text or at least one image attachment. The selected account must be active and owned by you. If platform is omitted, it comes from the account, or defaults to x.

Use either media_urls or asset_ids in one request. Uploaded asset IDs support X and Pinterest drafts. Pinterest uses content as the Pin description, up to 800 characters, and stores the Board, title, and link in platform_fields. Select a public Board before publishing or scheduling. Draft creation does not publish the post.

Request body

Name	Type	Description
platform_fields	object, optional	Platform-specific fields. For Pinterest: board_id, title (1–100 characters), and optional link. The Pin description is content.
account_id	UUID, optional	Connected account to use later when publishing or scheduling.
platform	string, optional	Lowercase platform identifier; must match account_id when supplied.
content	string, optional	Post text, up to 25,000 characters. Required unless an attachment is supplied. For Pinterest this is the Pin description, up to 800 characters.
media_urls	string[], optional	Public HTTPS image URLs. Up to 4 for X, 20 for LinkedIn or other draft platforms.
asset_ids	UUID[], optional	Up to 4 owned image assets from Media endpoints; X and Pinterest drafts (one image for Pinterest).

Example request

Terminal

curl -X POST "https://api.postpiper.ai/v1/posts" \
  -H "Authorization: Bearer $POSTPIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"<account-uuid>","content":"Hello from PostPiper"}'

Response

201 Created. Returns the draft post.

JSON

{
  "post": {
    "id": "<post-uuid>",
    "content": "Hello from PostPiper",
    "media_urls": [],
    "asset_ids": [],
    "platform": "x",
    "status": "draft",
    "account_id": "<account-uuid>",
    "created_at": "2030-10-12T01:00:00.000Z"
  }
}

Errors

400INVALID_CONTENT, MEDIA_FORMAT_CONFLICT, PLATFORM_MISMATCH, or TOO_MANY_MEDIA.
401Missing or invalid API key.
403API key lacks the required scope.
404ACCOUNT_NOT_FOUND or MEDIA_NOT_FOUND.