Skip to content
getgeolens.com

Get a story

GET
/stories/{story_id}
curl --request GET \
--url https://example.com/api/stories/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0

Read a story’s published document.

Scenes on maps the caller can’t read come back without their scene. An unpublished story is readable only by its owner and admins, with a null document. 404 when the caller can’t read the story.

story_id
required
Story Id
string format: uuid

Successful Response

Media type application/json
StoryResponse
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
document
required
Any of:
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
reader_theme
Any of:
ReaderTheme

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.

object
accent
Any of:
string
/^#[0-9a-fA-F]{6}$/
logo_url
Any of:
string
<= 2000 characters
font_family
Any of:
string
<= 100 characters /^ ?(?:"[A-Za-z0-9 -]+"|'[A-Za-z0-9 -]+'|[A-Za-z0-9-]+(?: [A-Za-z0-9-]+)*) ?(?:, ?(?:"[A-Za-z0-9 -]+"|'[A-Za-z0-9 -]+'|[A-Za-z0-9-]+(?: [A-Za-z0-9-]+)*) ?)*$/

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"
}