Create a story
const url = 'https://example.com/api/stories/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"title":"example","summary":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/stories/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "title": "example", "summary": "example" }'Create a private, unpublished story with an empty draft.
Authorizations
Section titled “ Authorizations ”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.
The sharing groups the story is shared with, by name.
object
Unique group identifier.
Group name.
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"}Conflict — resource state prevents the operation
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"}