P

Carousels & Infographics

Create carousel

Creates a multi-slide LinkedIn document-post carousel from a structured content outline (never HTML): Postiv's own carousel agent generates the branded slide HTML using the target profile's saved brand style. Created as a draft 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",
    "integrationId": 123
  }'
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.

integrationIdintrequired

Profile whose brand style (colors/fonts/templates) generates the slides.

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.

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[].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.

openInPostivUrlstring
warningsstring[]

Per-slide generation warnings, e.g. 'slide 3: ...'.

Errors

400missing_title / invalid_outline (0 slides or >10 slides)
404linkedin_profile_not_found
502carousel_generation_failed: generation produced zero slides

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 own slide-HTML agent (generateCarouselSlides) renders the visuals.