Skip to content
getgeolens.com

Create a story

POST
/stories/
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.

Media type application/json
StoryCreate
object
title
required
Title
string
>= 1 characters <= 200 characters
summary
Any of:
string
<= 2000 characters

Example generated

{
"title": "example",
"summary": "example"
}

Successful Response

Media type application/json
StoryDraftResponse
object
id
required
Id
string format: uuid
title
required
Title
string
summary
required
Any of:
string
visibility
required
StoredStoryVisibility

A story’s visibility as stored. A private story shared with groups is restricted: its groups’ members read it too.

string
Allowed values: private internal public restricted
created_by
required
Any of:
string format: uuid
published_at
required
Any of:
string format: date-time
cover_asset_id
required
Any of:
string format: uuid
created_at
required
Created At
string format: date-time
updated_at
required
Updated At
string format: date-time
can_edit
required
Can Edit
boolean
revision
required
Revision
integer
document
required
StoryDocument
object
version
required
Version
integer
chapters
required
Chapters
Array<object>
StoryChapter
object
id
required
Id
string format: uuid
title
Any of:
string
scene
Any of:
StoryScene
object
map_id
required
Map Id
string format: uuid
camera
required
StoryCamera
object
center
required
Center

Longitude, latitude.

array
>= 2 items <= 2 items
zoom
required
Zoom
number
<= 24
bearing
Bearing
number
0 >= -360 <= 360
pitch
Pitch
number
0 <= 85
layer_visibility
Layer Visibility

Visibility by map layer id. Layers the map no longer has are ignored, and a layer left out keeps its saved visibility.

object
<= 500 properties
key
additional properties
boolean
transition
Any of:
string
Allowed values: fly glide cut
scene_hidden
Scene Hidden

The chapter has a scene on a map you can’t read, so it’s shown without one.

boolean
blocks
Blocks
Array
One of: discriminator: type
MarkdownWidget
object
id
required
Id

Made by the client and stable across saves.

string format: uuid
title
Any of:
string
<= 120 characters
type
required
Type
string
Allowed value: markdown
v
required
V
integer
Allowed value: 1
config
required
MarkdownConfig
object
text
required
Text
string
<= 20000 characters
settings
Any of:
StorySettings
object
navigation
Navigation

Show the chapter navigation bar.

boolean
layout
Layout

Chapter panel beside the map or floating over it.

string
default: side
Allowed values: side floating
panel_position
Panel Position

Where a floating panel sits.

string
default: left
Allowed values: left right center
theme
Theme

Reader page theme; follow uses the reader’s.

string
default: follow
Allowed values: follow light dark
transition
Transition

How the map moves into a chapter whose scene sets no transition.

string
default: fly
Allowed values: fly glide cut
groups
Groups

The sharing groups the story is shared with, by name.

Array<object>
GroupRef
object
id
required
Id

Unique group identifier.

string format: uuid
name
required
Name

Group name.

string

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

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}

Unauthorized — missing or invalid credentials

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}

Forbidden — caller lacks write access

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}

Not found

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}

Conflict — resource state prevents the operation

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}

Validation error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}

Too many requests — retry after the advertised interval

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}
Retry-After
integer

Seconds until the request may be retried

Internal server error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}

Service unavailable — the database could not serve the request

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
code
Code

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.

string
action
Action

The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.

string
shared_maps
Shared Maps

The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.

Array<object>
object
key
additional properties
string

Example

{
"detail": "Dataset not found",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}