Update a story
const url = 'https://example.com/api/stories/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"title":"example","summary":"example","visibility":"private","cover_asset_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://example.com/api/stories/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "title": "example", "summary": "example", "visibility": "private", "cover_asset_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'Change a story’s title, summary, visibility or cover (owner or admin).
These apply at once, without Publish. A visibility wider than a map the
published story uses answers 409 maps_narrower_than_story; a narrower
one is always allowed. A story shared with groups stays restricted when
made private.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Request Bodyrequired
Section titled “ Request Bodyrequired ”Responses
Section titled “ Responses ”Successful Response
object
A story’s visibility as stored. A private story shared with groups is
restricted: its groups’ members read it too.
object
object
object
object
Longitude, latitude.
Visibility by map layer id. Layers the map no longer has are ignored, and a layer left out keeps its saved visibility.
object
The chapter has a scene on a map you can’t read, so it’s shown without one.
object
Made by the client and stable across saves.
An image uploaded to the host story.
object
Made by the client and stable across saves.
object
object
Made by the client and stable across saves.
object
object
Made by the client and stable across saves.
object
An http or https address; any other scheme is refused.
Open the link in a new tab.
object
Made by the client and stable across saves.
object
An https address on a host an admin approved for stories. Stored as given and never fetched by the server.
Names the frame for screen readers.
object
Made by the client and stable across saves.
object
An https address on a host an admin approved for stories. Stored as given and never fetched by the server.
Names the frame for screen readers.
object
Show the chapter navigation bar.
Chapter panel beside the map or floating over it.
Where a floating panel sits.
Reader page theme; follow uses the reader’s.
How the map moves into a chapter whose scene sets no transition.
An accent colour, a logo and a font family for reader-facing pages.
The frontend applies these as theme tokens only. A font is named, never fetched: the operator ships the font file, since the CSP allows no remote fonts.
Example
{ "visibility": "private", "document": { "chapters": [ { "scene": { "camera": { "bearing": 0, "pitch": 0 }, "transition": "fly" }, "scene_hidden": false, "blocks": [ { "type": "markdown", "v": 1 } ] } ], "settings": { "navigation": false, "layout": "side", "panel_position": "left", "theme": "follow", "transition": "fly" } }}Bad request — invalid payload
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Unauthorized — missing or invalid credentials
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Forbidden — caller lacks write access
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Not found
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Maps the story uses are narrower than its visibility (detail.code maps_narrower_than_story, the maps under detail.maps), a stale draft revision (stale_revision), or another change holding the story’s lock (no detail.code).
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Validation error
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Too many requests — retry after the advertised interval
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Headers
Section titled “ Headers ”Seconds until the request may be retried
Internal server error
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Service unavailable — the database could not serve the request
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}