Skip to contentDevelopersPrezly website
Stories

Convert HTML to Content

Convert HTML to structured content and inspect validation and diagnostics without saving a story.

Personal token scopes: stories:write. Your account must also have access to the requested data. Authentication

Read the guide

POST
/content/convert

Convert HTML into Prezly content format and validate it, without creating a story.

Nothing is created and nothing is uploaded, so this is the way to preview or check an import before committing to it.

Conversion runs the same deserializer the editor itself uses for pasting, so the result matches what pasting the same HTML into the editor would produce.

What to send

Reasonably clean, structural HTML — the article region rather than a whole page. This is a converter, not an extractor: it will faithfully carry across navigation, cookie banners and anything else it is given. Check diagnostics in the response to see what the conversion made of your input.

Titles

Prezly keeps the story title inside the content document, as a heading-one with role: title. A leading <h1> in your HTML is used when present; otherwise the title and subtitle fields are used to build that header.

Images

Images are not uploaded here. Each one becomes a placeholder:image node and its source URL is returned in images, so you can see what an import would fetch.

From a URL (beta)

Send url instead of html to see what importing the story at that address would produce. This is in beta: review the result, as the story can come out incomplete or with parts of the page that are not the story.

Personal access tokens: stories:write. Every listed scope is required; the token owner's permissions, feature availability and newsroom access still apply.

Authorization

API_key
headerAuthorizationBearer <token>

Bearer authentication using an integration API key, or a personal access token only where the operation explicitly supports it. Every listed personal-token scope is required; owner permissions and newsroom access still apply.

Request Body

application/json
  1. body

Send exactly one of html or url.

html*string

The HTML to convert. Maximum 20MB.

url?string

Beta. The address of a published story, instead of html. The story is picked out of the page automatically and can miss content or include parts of the page that are not the story, so review the result before publishing. See Importing from a URL. Send either html or url, not both; nodes cannot be combined with url.

Formaturi
title?string

Story title, used only when the HTML has no leading heading to promote.

subtitle?string

Story subtitle. Used when the HTML has no subtitle heading of its own.

nodes?array<>

Rich nodes that cannot be recovered from HTML — galleries, contacts, videos, embeds, bookmarks, attachments, dividers and buttons. Give a node a ref and place [[prezly-node:<ref>]] in its own paragraph in the HTML to control where it lands; without a ref it is appended.

Response Body

OK

application/json
  1. response
valid?boolean

Whether the produced document is structurally valid.

accepted?boolean

Whether the same validator the story-create path uses accepts the document.

content?

The content-format document.

images?array<>

Image sources found in the HTML, in document order. An import would upload these; this endpoint does not.

diagnostics?array<>

What the conversion found — empty blocks, unresolved images, unsupported elements, a missing title. Each carries a code, a level and a message.

source?

Only when importing from a url (beta): where the story came from and how it was picked out of the page. published_at and language are reported, not applied.

Example Request
curl -X POST 'https://api.prezly.com/v2/content/convert' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "valid": true,  "accepted": true,  "content": {},  "images": [    {}  ],  "diagnostics": [    {}  ],  "source": {    "url": "string",    "final_url": "string",    "canonical": "string",    "slug": "string",    "extractor": "llm",    "model": "string",    "published_at": "2019-08-24T14:15:22Z",    "language": "string",    "lead_image": "string"  }}