Import HTML into an Existing Story
Replace a named story’s content from HTML while retaining its identity and translation relationships.
Personal token scopes: stories:write. Your account must also have access to the requested data. Authentication
The same import as Import Story from HTML, into a story that already exists: its content is replaced by what the HTML converts to.
Which story is never inferred from the payload — there is no matching on slug or title. A re-import is exactly the situation where overwriting the wrong story would go unnoticed, so the story is named in the URL.
The story keeps its uuid and its place in a translation group — neither can be set through this endpoint, or through any story update — so everything linking to it survives. That is what makes this different from deleting the story and importing again, and what a migration run more than once needs: the second run updates what the first made.
Its other fields behave exactly as they do on Update Story: unchanged unless you send
them. Send custom_slug and the slug changes; leave it out and it does not.
Two things it will not do:
- Move the story. Sending
newsroomis refused — moving a story between sites isPOST /v2/stories/{story_id}/move, which has its own rules about what moving does to a story's contacts and categories. - Delete the images the story had. An earlier revision may still reference them.
Send url instead of html (beta) to replace the story's content with the story
published at that address — review the result before publishing it.
Personal access tokens: stories:write. Every listed scope is required; the token owner's permissions, feature availability and newsroom access still apply.
API_keyAuthorizationBearer <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.
story_id*stringStory UUID
application/json- body
The story fields both HTML-import endpoints pass straight through to the ordinary create and update paths, where they are validated exactly as they are there.
title and subtitle are deliberately not here: format_version 6 keeps them inside the
content document, so the import endpoints hand them to the converter rather than to the story.
Neither is content — that is what the import produces.
seo_settings is not here either, because creating a story does not take it. It is on the
import-into-an-existing-story endpoint, which does.
html*stringThe HTML to import. Maximum 20MB.
url?stringBeta. 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.
urititle?stringStory title, used when the HTML has no leading heading to promote.
Required unless the HTML carries its own <h1>.
subtitle?stringnodes?array<>Rich nodes that cannot be recovered from HTML. See Convert HTML to Content.
custom_slug?stringThe story's URL slug. Left as it is when not sent.
culture?LocaleCodeLanguage code (ISO 639-1 or ISO 639-2), with optional script designator (ISO 15924) and optional region code (ISO 3166-1).
[a-z]{2,3}(_[A-Z][a-z]{3})?(_[A-Z]{2})?2 <= lengthvisibility?string"public""embargo""private""confidential"published_at?stringdate-timecategories?array<integer>Category ids. Fractions are refused, so this is an integer list.
tags?array<string>preview_image?Object containing info about an uploaded image.
See Images and Files on how to handle images.
social_image?Object containing info about an uploaded image.
See Images and Files on how to handle images.
social_text?stringseo_settings?Only on this endpoint — creating a story does not take it — and only for accounts with the SEO settings feature; without it the field is refused rather than ignored.
OK
application/json- response
story?diagnostics?array<>What the conversion and the media uploads found. Worth checking even on success — an image that failed to upload is reported here.
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.
curl -X POST 'https://api.prezly.com/v2/stories/string/import-from-html' \ -H 'Content-Type: application/json' \ -d '{}'{ "story": { "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f", "id": 0, "thumbnail_url": "http://example.com", "title": "string", "subtitle": "string", "intro": "string", "culture": [ { "code": "en", "name": "string", "direction": "ltr", "language_code": "en", "native_name": "string" } ], "format_version": 1, "slug": "string", "language": "string", "status": "uninitialized", "lifecycle_status": "uninitialized", "publication_status": "uninitialized", "visibility": "private", "is_archived": true, "is_finalized": true, "is_published": true, "is_draft": true, "is_embargo": true, "is_private": true, "is_scheduled": true, "is_analytics_available": true, "is_sharable": true, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "published_at": "2019-08-24T14:15:22Z", "scheduled_at": "2019-08-24T14:15:22Z", "author": { "id": 0, "email": "http://example.com", "name": "string", "display_name": "string", "first_name": "string", "last_name": "string", "avatar_url": "http://example.com" }, "newsroom": { "id": 0, "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f", "name": "string", "display_name": "string", "subdomain": "string", "thumbnail_url": "http://example.com", "timezone": "europe/london", "is_active": true, "is_archived": true, "is_online": true, "is_offline": true, "is_multilingual": true, "url": "http://example.com", "links": { "media_gallery_api": "http://example.com", "room_contacts_api": "http://example.com", "analytics_and_visibility_settings": "http://example.com", "categories_management": "http://example.com", "company_info_settings": "http://example.com", "contacts_management": "http://example.com", "domain_settings": "http://example.com", "edit": "http://example.com", "gallery_management": "http://example.com", "hub_settings": "http://example.com", "languages": "http://example.com", "look_and_feel_settings": "http://example.com", "manual_subscription_management": "http://example.com", "privacy_settings": "http://example.com", "widget_settings": "http://example.com" } }, "oembed": { "url": "http://example.com", "type": "video", "version": "1.0", "title": "string", "description": "string", "author_name": "string", "author_url": "http://example.com", "provider_name": "string", "provider_url": "http://example.com", "cache_age": 0, "html": "string", "thumbnail_url": "http://example.com", "thumbnail_width": 1, "thumbnail_height": 1, "screenshot_url": "http://example.com" }, "links": { "api": "string", "preview": "string", "edit": "string", "sharing": "string", "duplicate": "string", "translate": "string", "analytics": "string", "delete": "string", "publication_api": "string", "reports_api": "string", "short": "string", "newsroom_view": "http://example.com", "newsroom_preview": "http://example.com" }, "categories": [ { "id": 0, "display_name": "string", "display_description": "string", "i18n": { "[a-z]{2,3}(_[A-Z][a-z]{3})?(_[A-Z]{2})?": { "name": "string", "description": "string", "slug": "string", "locale": { "code": "en", "name": "string", "direction": "ltr", "language_code": "en", "native_name": "string" } } }, "stories_number": 0 } ], "translations": [ { "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f", "id": 0, "thumbnail_url": "http://example.com", "title": "string", "culture": { "code": "en", "name": "string", "direction": "ltr", "language_code": "en", "native_name": "string" }, "language": "string", "status": "uninitialized", "lifecycle_status": "uninitialized", "publication_status": "uninitialized", "visibility": "public", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "published_at": "2019-08-24T14:15:22Z", "scheduled_at": "2019-08-24T14:15:22Z", "author": { "id": 0, "email": "http://example.com", "name": "string", "display_name": "string", "first_name": "string", "last_name": "string", "avatar_url": "http://example.com" }, "newsroom": { "id": 0, "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f", "name": "string", "display_name": "string", "subdomain": "string", "thumbnail_url": "http://example.com", "timezone": "europe/london", "is_active": true, "is_archived": true, "is_online": true, "is_offline": true, "is_multilingual": true, "url": "http://example.com", "links": { "media_gallery_api": "http://example.com", "room_contacts_api": "http://example.com", "analytics_and_visibility_settings": "http://example.com", "categories_management": "http://example.com", "company_info_settings": "http://example.com", "contacts_management": "http://example.com", "domain_settings": "http://example.com", "edit": "http://example.com", "gallery_management": "http://example.com", "hub_settings": "http://example.com", "languages": "http://example.com", "look_and_feel_settings": "http://example.com", "manual_subscription_management": "http://example.com", "privacy_settings": "http://example.com", "widget_settings": "http://example.com" } }, "url": "http://example.com", "oembed": { "url": "http://example.com", "type": "video", "version": "1.0", "title": "string", "description": "string", "author_name": "string", "author_url": "http://example.com", "provider_name": "string", "provider_url": "http://example.com", "cache_age": 0, "html": "string", "thumbnail_url": "http://example.com", "thumbnail_width": 1, "thumbnail_height": 1, "screenshot_url": "http://example.com" }, "slug": "string" } ], "coverage_number": 0, "images_number": 0, "videos_number": 0, "last_coverage_at": "2019-08-24T14:15:22Z", "content_version": 0 }, "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" }}