Posts
Create draft posts and fetch their status.
Create posts from generation outputs or custom content. Posts start as drafts that you can review before publishing.
Looking for publish, schedule, cancel, or list/retry? Those live on Publish & schedule and Post items. Media and caption limits are under Post types.
Create Post
POST /api/v1/posts
Create a post from generation outputs or custom content. Posts start as drafts that you can review before publishing.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
generation_id | string | No | Caption generation ID to populate content from |
items | array | Yes | Post items — one per post type you want to publish (1–13, matching the supported post types) |
Post Item Object
| Field | Type | Required | Description |
|---|---|---|---|
post_type | string | Yes | Target post type (e.g., instagram-reel, tiktok-video) |
content | string | Yes* | Caption text for this platform |
title | string | No | Title (required for YouTube post types) |
media_ids | string[] | No | Media to attach (uploaded or generated images) |
* Required for captioned post types unless generation_id fills them. Not required for instagram-story or facebook-story (media-only; any content you send is ignored).
Examples
From a Generation
Create a post using outputs from a completed caption generation:
curl -X POST https://powerpost.ai/api/v1/posts \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"generation_id": "550e8400-e29b-41d4-a716-446655440000",
"items": [
{
"post_type": "instagram-reel",
"media_ids": ["img-001-abcd-efgh"]
},
{
"post_type": "tiktok-video",
"media_ids": ["img-001-abcd-efgh"]
}
]
}'Custom Content
Create a post with your own content — no generation needed:
curl -X POST https://powerpost.ai/api/v1/posts \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"post_type": "x-post",
"content": "Just shipped the biggest update of the year. Thread below."
},
{
"post_type": "instagram-feed",
"content": "Our biggest update of the year is live! Check link in bio for details.",
"media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}
]
}'YouTube Post
YouTube requires a title in addition to the description:
curl -X POST https://powerpost.ai/api/v1/posts \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"post_type": "youtube-short",
"title": "We Just Shipped Dark Mode",
"content": "Dark mode is finally here across all our apps. #darkmode #tech",
"media_ids": ["vid-001-abcd-efgh"]
}
]
}'Response
{
"post_id": "post-550e8400-e29b-41d4-a716-446655440000",
"status": "draft",
"created_at": "2026-01-10T18:30:00Z",
"items": [
{
"item_id": "item-001",
"post_type": "instagram-reel",
"platform": "instagram",
"content": "Dark mode is here! Your late-night scrolling just got easier... #DarkMode",
"media_ids": ["img-001-abcd-efgh"],
"status": "draft"
},
{
"item_id": "item-002",
"post_type": "tiktok-video",
"platform": "tiktok",
"content": "POV: your eyes at 2am finally getting some relief... #darkmode #tech",
"media_ids": ["img-001-abcd-efgh"],
"status": "draft"
},
{
"item_id": "item-003",
"post_type": "youtube-short",
"platform": "youtube",
"title": "Dark mode launch",
"content": "We finally shipped dark mode...",
"media_ids": ["img-001-abcd-efgh"],
"status": "draft"
}
]
}title only appears on items where it was set on input (typically YouTube post types). Item
fields like platform_post_id, platform_url, posted_at, and error only appear after
publishing — see Get Post.
Get Post
GET /api/v1/posts/{id}
Retrieve the details and status of a post.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The post ID |
Example
curl https://powerpost.ai/api/v1/posts/post-550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID"Response
{
"post_id": "post-550e8400-e29b-41d4-a716-446655440000",
"status": "sent",
"created_at": "2026-01-10T18:30:00Z",
"items": [
{
"item_id": "item-001",
"post_type": "instagram-reel",
"platform": "instagram",
"content": "Dark mode is here!...",
"media_ids": ["img-001-abcd-efgh"],
"status": "posted",
"platform_post_id": "17898455678012345",
"platform_url": "https://instagram.com/p/CxYz123abc/",
"posted_at": "2026-01-10T18:35:02Z"
},
{
"item_id": "item-002",
"post_type": "tiktok-video",
"platform": "tiktok",
"content": "POV: your eyes at 2am...",
"media_ids": ["img-001-abcd-efgh"],
"status": "posted",
"platform_post_id": "7234567890123456789",
"platform_url": "https://www.tiktok.com/@user/video/7234567890123456789",
"posted_at": "2026-01-10T18:35:14Z"
},
{
"item_id": "item-003",
"post_type": "youtube-short",
"platform": "youtube",
"title": "Dark mode launch",
"content": "We finally shipped dark mode...",
"media_ids": ["img-001-abcd-efgh"],
"status": "failed",
"error": "Upload exceeded daily quota"
}
]
}Item fields are conditional. title is included for items that have one (typically YouTube
post types). platform_post_id, platform_url, and posted_at appear only after a successful
publish. error appears only when the item is in failed status.
Post Status Values
Post Status
| Status | Description |
|---|---|
draft | Created, not yet published |
scheduled | Waiting on a delayed publish job to fire |
sent | First publish has started; items own outcomes |
Item Status
| Status | Description |
|---|---|
draft | Not yet published |
posting | Publishing in progress |
posted | Successfully published |
failed | Failed (see error field) |
skipped | Target platform had no active connection, so it wasn't posted |
Related
- Publish & schedule — Publish, schedule, cancel, settings
- Post items — List published items and retry failures
- Post types — Supported types and media/caption limits
- Errors — Global error codes