Content formats

A story has two relevant versions: format_version on the story resource and version inside its content document. They describe different things. For a new integration, request story format v6 explicitly and use a renderer that supports it.

Request the format your renderer supportsCopy Anchor Link

Use the token and story UUID from Your first API request, replacing YOUR_STORY_UUID:

curl --fail-with-body --silent --show-error 'https://api.prezly.com/v2/stories/YOUR_STORY_UUID' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json; content-format=v6'

The API converts content for the response when needed. This is a read: it does not save a converted story or change the format in which it is stored. The returned format_version tells you how to interpret the returned content.

Do not rely on an omitted content-format header choosing the latest format. The API retains compatibility defaults for older clients. When using the JavaScript SDK, pass formats: [Story.FormatVersion.SLATEJS_V6] to the story operation.

Parse the response, then the contentCopy Anchor Link

The HTTP response is JSON, but story.content is itself a JSON-encoded string for structured formats. Parsing the HTTP response does not parse that inner document.

This abbreviated response shows the two layers:

{
  "story": {
    "format_version": 6,
    "content": "{\"type\":\"document\",\"version\":\"2.6\",\"children\":[]}"
  }
}

The empty document above illustrates encoding, not a complete article. Parse story.content once to obtain the document object. Do not pass the string directly to a structured renderer or insert it as HTML. See Story rendering for a working example.

Understand the version numbersCopy Anchor Link

The current editor produces v6 stories with a 2.6 document. Do not compare these values as if they used the same numbering scheme.

What changed between story formats?Copy Anchor Link

There is no v2 story format to target in a new integration. Package versions such as the renderer's npm version are another independent version series.

Handle title and header media onceCopy Anchor Link

For v4 and later, the document's opening nodes carry the title and subtitle, identified by role: "title" and role: "subtitle". A header image or media placeholder can precede them. The story's plaintext title and subtitle are useful for cards and metadata; rendering them above the entire document can duplicate the visible headings.

Either render the whole document, including its title, or render those fields separately and override the corresponding document nodes. Do the same deliberately for header media. Rich content shows how to override title rendering.

Keep conversion and renderer support alignedCopy Anchor Link

Requesting an older format can change the presentation of newer features. For example, conversion from v6 to v5 turns a callout into a quote and removes the highlighted mark. Prefer updating the renderer and continuing to request v6 when those features matter.

If the request fails, inspect the HTTP status and error code rather than guessing a different format. An unsupported format name can return 406 with invalid_content_format; conversion failures can also be reported as request errors. See Handling errors.

To retrieve full content, use Get Story. Story lists normally return summary fields; request include=content if you need content in a list response. Format negotiation and field inclusion are separate choices.

To write v6 content rather than only render it, follow Creating and updating stories.