Edit a post

Change the caption, the media, and the slides one by one.

View as Markdown Open in Claude Open in ChatGPT

A carousel has three editable surfaces: the caption, the media list, and the slides. The caption goes in PATCH /posts/{id}, which also edits the other five formats; see Read and edit for those.

The caption

curl -X PATCH -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"caption":"the new caption"}' \
  "https://api.posttar.com/v1/posts/dd8d142c-..."

Limited to 2200 characters, the same ceiling Instagram has.

The slides

GET /posts/{id} returns them in content.slides, in order, each with its id, its layout and its text fields. From there:

PATCH /slides/{id} changes the text of one slide
POST /slides/{id}/variant swaps its layout for another
POST /slides/{id}/reimagine regenerates its image
POST /posts/{id}/slides adds one at the end
DELETE /slides/{id} removes one
POST /posts/{id}/slides/order reorders the whole set

Image changes are metered. GET /posts/{id}/edit-budget tells you how many you have used and how many are left on that post, as used, cap and remaining.

The one that trips everyone: `fields` against `design`

A slide comes back with two objects that look interchangeable and are not. fields is the list of text boxes the slide's layout declares, and it is the ONLY thing PATCH /slides/{id} accepts. design is everything else the slide carries (leftover keys from the layout, or the whole piece when an AI drew it), and sending any of it is refused.

{
  "id": "1663f551-...",
  "variant": "da7ad87a-...",
  "fields": [
    { "name": "headline", "value": "Are you looking at the wrong metric?" },
    { "name": "body", "value": "A simple guide to what reach and retention really say." },
    { "name": "image", "value": "https://.../2264277c.webp" }
  ],
  "design": { "items": [], "number": null, "caption": null, "eyebrow": null }
}

So the edit is {"fields": {"headline": "..."}}, keyed by the name you read, and never {"design": ...}. Send only the fields you are changing; the others stay.

What you read	What it means	How to change it
`variant` set, `fields` with entries	A carousel slide built from a layout	`PATCH /slides/{id}` with those field names
`variant: null`, `fields: []`	The whole slide is one image an AI drew (`premium_carousel`, `infographic`)	`POST /slides/{id}/reimagine` with a sentence. There is nothing for `PATCH` to change
a field of type image	The slide's picture. Its value is an address, and `PATCH /slides/{id}` takes it like any other field	Only an address already stored at Posttar. Anywhere else is refused

A field name that the slide's layout does not declare is refused with invalid_input and the name in the message, never ignored. That is deliberate: a silently dropped field would look exactly like a successful edit.

Rewrite the first slide and reorder

Read, edit one, then set the order explicitly.

Read the post to get the slide ids and their current order, in content.slides.

curl -H "Authorization: Bearer $POSTTAR_KEY" "https://api.posttar.com/v1/posts/dd8d142c-..."

Change the text of one slide.

curl -X PATCH -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"fields":{"title":"A sharper hook"}}' \
  "https://api.posttar.com/v1/slides/9f2a1c70-..."

Set the order. Send the complete list of slide ids, in the new order.

curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"order":["9f2a1c70-...","2b7d4e91-...","c1a8f350-..."]}' \
  "https://api.posttar.com/v1/posts/dd8d142c-.../slides/order"

The media

POST /posts/{id}/media replaces the post's media list with the one you send, in a media field. At most 10 items, which is the Instagram carousel limit, and an empty list removes the media. Use it when you render images yourself and want Posttar to publish those instead of the generated ones.