Generations

List Generations

GET /api/v1/content/generations

List your caption generations with optional filtering.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `pending`, `processing`, `completed`, `failed`
`limit`	number	No	Results per page (1-100, default: 20)
`cursor`	string	No	Cursor for pagination (from `next_cursor`)

Example

curl "https://powerpost.ai/api/v1/content/generations?status=completed&limit=10" \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

Response

{
  "data": [
    {
      "generation_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "prompt": "We just shipped dark mode",
      "platforms": ["tiktok", "instagram"],
      "research_mode": "regular",
      "credits_used": 10,
      "created_at": "2026-01-10T18:30:00Z"
    },
    {
      "generation_id": "661f9511-f3ac-52e5-b827-557766551111",
      "status": "completed",
      "prompt": "New feature: AI-powered search",
      "platforms": ["x", "facebook"],
      "research_mode": "deep",
      "credits_used": 15,
      "created_at": "2026-01-09T12:00:00Z"
    }
  ],
  "next_cursor": "gen_cursor_abc123",
  "has_more": true
}

The list endpoint does not include outputs. Use the Get Generation endpoint below to retrieve full outputs for a specific generation.

Get Generation

GET /api/v1/content/generations/{id}

Retrieve the status and outputs of a generation.

Request

Path Parameters

Parameter	Type	Description
`id`	string	The generation ID

Headers

Header	Value
`x-api-key`	Your API key
`X-Workspace-Id`	Your workspace ID

Example Request

curl https://powerpost.ai/api/v1/content/generations/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

Response (Processing)

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "prompt": "We just shipped dark mode",
  "platforms": ["tiktok", "instagram"],
  "research_mode": "regular",
  "credits_used": 10,
  "created_at": "2026-01-10T18:30:00Z"
}

Response (Completed)

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "prompt": "We just shipped dark mode",
  "platforms": ["tiktok", "instagram"],
  "research_mode": "regular",
  "credits_used": 10,
  "created_at": "2026-01-10T18:30:00Z",
  "outputs": {
    "tiktok": "🌙 Dark mode activated! POV: your eyes at 2am finally getting some relief... #darkmode #tech #appupdate",
    "instagram": "✨ Dark mode is here!\n\nYour late-night scrolling just got easier on the eyes... #DarkMode #ProductUpdate"
  }
}

YouTube outputs have a different structure with separate title and description fields:

"youtube": {
  "title": "We Just Shipped Dark Mode",
  "description": "Dark mode is finally here across all our apps... #darkmode"
}

All other platforms output a single string with hashtags included.

Response (Failed)

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "prompt": "We just shipped dark mode",
  "platforms": ["tiktok", "instagram"],
  "research_mode": "regular",
  "credits_used": 0,
  "created_at": "2026-01-10T18:30:00Z",
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Failed to generate content. Please try again."
  }
}

Response Fields

Field	Type	Description
`generation_id`	string	Unique generation ID
`status`	string	Current status (see below)
`prompt`	string	The original input prompt
`platforms`	array	Platforms content was generated for
`research_mode`	string	Research mode used
`credits_used`	number	Credits charged for this generation
`created_at`	string	ISO 8601 timestamp
`outputs`	object	Platform content (only when `completed`)
`error`	object	Error details (only when `failed`)

Status Values

Status	Description
`pending`	Queued, not yet started
`processing`	Generation is running
`completed`	Outputs are ready
`failed`	Generation failed

Polling Strategy

We recommend polling every 2-3 seconds until status is completed or failed:

async function waitForGeneration(generationId, apiKey, workspaceId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`https://powerpost.ai/api/v1/content/generations/${generationId}`, {
      headers: { 'x-api-key': apiKey, 'X-Workspace-Id': workspaceId },
    })
    const data = await res.json()

    if (data.status === 'completed') return data.outputs
    if (data.status === 'failed') throw new Error(data.error.message)

    await new Promise((r) => setTimeout(r, 2000))
  }
  throw new Error('Generation timed out')
}

For production, consider using webhooks instead of polling.

Errors

Code	Description
400	Invalid `status`, `limit`, or `cursor` (List Generations only)
401	Invalid API key
403	API key is missing the `content:read` scope
404	Generation not found (Get Generation only)
429	Rate limit exceeded

Regenerate Content

POST /api/v1/content/generations/{id}/regenerate

Regenerate caption content for one platform on a completed generation. Optionally pass free-text feedback (the same “tweak this draft” flow as the studio UI). Returns the new content for that platform immediately — no polling.

Uses the original research and hashtag data from the generation. Costs 1 credit.

Path Parameters

Parameter	Type	Description
`id`	string	The generation ID

Headers

Header	Value
`x-api-key`	Your API key
`X-Workspace-Id`	Your workspace ID
`Content-Type`	`application/json`

Body

Field	Type	Required	Description
`platform`	string	Yes	Platform to rewrite. Must be one of the generation’s original platforms.
`refinement`	string	No	Feedback for the rewrite, e.g. `"be more friendly"` or `"shorter, less hype"`. Max 2000 characters.

Example

curl -X POST https://powerpost.ai/api/v1/content/generations/550e8400-e29b-41d4-a716-446655440000/regenerate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "refinement": "be more friendly and casual"
  }'

Response

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "instagram",
  "content": "Hey friends — dark mode is finally here...\n\n#DarkMode #ProductUpdate",
  "credits_used": 1,
  "remaining_credits": 42
}

YouTube and TikTok return a structured object for content (title + description) instead of a plain string. Other platforms return a string. The generation’s stored outputs are updated in place — a later GET includes the new version.

Response Fields

Field	Type	Description
`generation_id`	string	The generation that was updated
`platform`	string	Platform that was regenerated
`content`	string\|object	New caption for that platform
`credits_used`	number	Credits charged (always `1`)
`remaining_credits`	number	Account balance after the charge

Errors

Code	Description
400	Invalid body, generation not completed, platform not on generation, or missing research data
401	Invalid API key
402	Insufficient credits
403	API key is missing the `content:generate` scope
404	Generation not found
429	Rate limit exceeded

List Generations

GET /api/v1/content/generations

List your caption generations with optional filtering.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `pending`, `processing`, `completed`, `failed`
`limit`	number	No	Results per page (1-100, default: 20)
`cursor`	string	No	Cursor for pagination (from `next_cursor`)

Example

curl "https://powerpost.ai/api/v1/content/generations?status=completed&limit=10" \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

Response

{
  "data": [
    {
      "generation_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "prompt": "We just shipped dark mode",
      "platforms": ["tiktok", "instagram"],
      "research_mode": "regular",
      "credits_used": 10,
      "created_at": "2026-01-10T18:30:00Z"
    },
    {
      "generation_id": "661f9511-f3ac-52e5-b827-557766551111",
      "status": "completed",
      "prompt": "New feature: AI-powered search",
      "platforms": ["x", "facebook"],
      "research_mode": "deep",
      "credits_used": 15,
      "created_at": "2026-01-09T12:00:00Z"
    }
  ],
  "next_cursor": "gen_cursor_abc123",
  "has_more": true
}

The list endpoint does not include outputs. Use the Get Generation endpoint below to retrieve full outputs for a specific generation.

Parameter	Type	Description
`id`	string	The generation ID

Headers

Header	Value
`x-api-key`	Your API key
`X-Workspace-Id`	Your workspace ID

Example Request

curl https://powerpost.ai/api/v1/content/generations/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

Response (Processing)

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "prompt": "We just shipped dark mode",
  "platforms": ["tiktok", "instagram"],
  "research_mode": "regular",
  "credits_used": 10,
  "created_at": "2026-01-10T18:30:00Z"
}

Response (Completed)

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "prompt": "We just shipped dark mode",
  "platforms": ["tiktok", "instagram"],
  "research_mode": "regular",
  "credits_used": 10,
  "created_at": "2026-01-10T18:30:00Z",
  "outputs": {
    "tiktok": "🌙 Dark mode activated! POV: your eyes at 2am finally getting some relief... #darkmode #tech #appupdate",
    "instagram": "✨ Dark mode is here!\n\nYour late-night scrolling just got easier on the eyes... #DarkMode #ProductUpdate"
  }
}

YouTube outputs have a different structure with separate title and description fields:

"youtube": {
  "title": "We Just Shipped Dark Mode",
  "description": "Dark mode is finally here across all our apps... #darkmode"
}

All other platforms output a single string with hashtags included.

Response (Failed)

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "prompt": "We just shipped dark mode",
  "platforms": ["tiktok", "instagram"],
  "research_mode": "regular",
  "credits_used": 0,
  "created_at": "2026-01-10T18:30:00Z",
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Failed to generate content. Please try again."
  }
}

Response Fields

Field	Type	Description
`generation_id`	string	Unique generation ID
`status`	string	Current status (see below)
`prompt`	string	The original input prompt
`platforms`	array	Platforms content was generated for
`research_mode`	string	Research mode used
`credits_used`	number	Credits charged for this generation
`created_at`	string	ISO 8601 timestamp
`outputs`	object	Platform content (only when `completed`)
`error`	object	Error details (only when `failed`)

Status Values

Status	Description
`pending`	Queued, not yet started
`processing`	Generation is running
`completed`	Outputs are ready
`failed`	Generation failed

Polling Strategy

We recommend polling every 2-3 seconds until status is completed or failed:

async function waitForGeneration(generationId, apiKey, workspaceId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`https://powerpost.ai/api/v1/content/generations/${generationId}`, {
      headers: { 'x-api-key': apiKey, 'X-Workspace-Id': workspaceId },
    })
    const data = await res.json()

    if (data.status === 'completed') return data.outputs
    if (data.status === 'failed') throw new Error(data.error.message)

    await new Promise((r) => setTimeout(r, 2000))
  }
  throw new Error('Generation timed out')
}

For production, consider using webhooks instead of polling.

Errors

Code	Description
400	Invalid `status`, `limit`, or `cursor` (List Generations only)
401	Invalid API key
403	API key is missing the `content:read` scope
404	Generation not found (Get Generation only)
429	Rate limit exceeded

Regenerate Content

POST /api/v1/content/generations/{id}/regenerate

Uses the original research and hashtag data from the generation. Costs 1 credit.

Path Parameters

Parameter	Type	Description
`id`	string	The generation ID

Headers

Header	Value
`x-api-key`	Your API key
`X-Workspace-Id`	Your workspace ID
`Content-Type`	`application/json`

Body

Field	Type	Required	Description
`platform`	string	Yes	Platform to rewrite. Must be one of the generation’s original platforms.
`refinement`	string	No	Feedback for the rewrite, e.g. `"be more friendly"` or `"shorter, less hype"`. Max 2000 characters.

Example

curl -X POST https://powerpost.ai/api/v1/content/generations/550e8400-e29b-41d4-a716-446655440000/regenerate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "refinement": "be more friendly and casual"
  }'

Response

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "instagram",
  "content": "Hey friends — dark mode is finally here...\n\n#DarkMode #ProductUpdate",
  "credits_used": 1,
  "remaining_credits": 42
}

Response Fields

Field	Type	Description
`generation_id`	string	The generation that was updated
`platform`	string	Platform that was regenerated
`content`	string\|object	New caption for that platform
`credits_used`	number	Credits charged (always `1`)
`remaining_credits`	number	Account balance after the charge

Errors

Code	Description
400	Invalid body, generation not completed, platform not on generation, or missing research data
401	Invalid API key
402	Insufficient credits
403	API key is missing the `content:generate` scope
404	Generation not found
429	Rate limit exceeded

Generations

On this page

Generations

On this page