P

Carousels & Infographics

Create carousel

Creates an editable multi-slide carousel draft from a structured content outline (never HTML). LinkedIn only: an X account returns 400 linkedin_only. Omit integrationId to use the selected template or default styling without profile branding; supply a connected LinkedIn profile or company page for profile branding. Created with no rendered preview.

POST/api/public/carousels
cURLPOST /api/public/carousels
curl -X POST https://postiv.ai/api/public/carousels \
  -H "Authorization: Bearer pk_postiv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch lessons"
  }'
200Response
{
  "success": true,
  "carousel": {
    "id": "car1...",
    "title": "5 Content Mistakes",
    "status": "draft",
    "integrationId": 1234,
    "planItemId": null,
    "createdAt": "2026-07-19T09:10:00.000Z"
  },
  "versionId": "cv1...",
  "versionNumber": 1,
  "slideCount": 6,
  "slides": [
    {
      "index": 0,
      "title": "5 Content Mistakes",
      "textPreview": "Most B2B content fails because..."
    }
  ],
  "openInPostivUrl": "https://postiv.ai/app/create?carouselId=car1...",
  "warnings": []
}

Authorization

Requires an organization API key with the posts:write scope, sent as Authorization: Bearer or x-api-key.

Body parameters

titlestringrequired

1-240 chars, internal library title.

integrationIdint

Optional positive LinkedIn profile or company page ID for branding (LinkedIn only: an X account returns 400 linkedin_only). Omit for an unassigned draft using the selected template or default styling; null is not accepted. Required when planItemId is supplied. Scheduling and publishing require a connected profile.

styleIdstring

Exact styleId from list_visual_templates (format carousel). global:freeform has no template: a designer draws every slide around the outline copy in the Brand Kit, with images only from outline.slides[].assetHints.

outline.topicstringrequired
outline.targetAudiencestring
outline.contentTypestring

e.g. educational, listicle, case study, story.

outline.objectivestring
outline.narrativeArcstring
outline.styleInstructionsstring

Freeform visual direction layered on the saved brand style. With styleId global:freeform, the look the designer follows.

outline.backgroundStylestring
One of:nonegriddotsdiagonalwavessubtle-noisegradient-only
outline.themeOverride.backgroundColorstring

Hex; overrides the saved brand theme for this carousel only.

outline.themeOverride.textColorstring
outline.themeOverride.primaryColorstring
outline.themeOverride.accentColorstring
outline.slides[]arrayrequired

1-10 slides (10 max enforced; app-level guidance says 5-8 is the LinkedIn sweet spot).

outline.slides[].slideTypestringrequired

e.g. cover, content, list, quote, stats, comparison, cta.

outline.slides[].headlinestringrequired
outline.slides[].subheadlinestring
outline.slides[].bodystring
outline.slides[].calloutstring
outline.slides[].items[]array

Max 8, each { label, description? }.

outline.slides[].dataPointobject

{ value, label } hero stat.

outline.slides[].imageUrls[]string[]

Max 3 public URLs.

outline.slides[].assetHints[]array

Freeform (styleId global:freeform) only; templates ignore them. Max 4, each { kind: logo | image | screenshot | website-screenshot, topic, label?, scope?: any | library | web }. Search-only, never AI generated; topic {asset=ID} uses that media-library image directly. Unresolved assets come back in warnings.

outline.slides[].layoutstring
outline.slides[].designNotesstring
planItemIduuid

Links to a Bob plan item and marks it drafted.

Response

The created carousel with slide text summaries.

carousel.id / title / status / integrationId / planItemId / createdAtmixed
versionIduuid
versionNumberint

1 for a new carousel.

slideCountint
slides[].index / title / textPreviewmixed

textPreview is HTML-stripped, truncated to 200 chars.

appliedStyleobject

Freeform only: { styleId: 'global:freeform', name: 'Freeform', explicitlySelected: true }.

openInPostivUrlstring
warningsstring[]

Profile-branding notices and per-slide generation warnings, e.g. 'slide 3: ...'.

Errors

400missing_title / invalid_outline (0 slides or >10 slides)
400missing_integration_id: planItemId was supplied without integrationId
400linkedin_only: integrationId is an X account
404integration_not_found: integrationId is not an account in this workspace / linkedin_profile_not_found: the LinkedIn profile is not active
502carousel_generation_failed: generation produced zero slides, or the Freeform designer failed

Good to know

  • Status is 201 Created. Always call render-carousel next: no preview images exist yet. The model must supply CONTENT only; Postiv's shared slide generator fills editable canvas templates.