Skip to content
getgeolens.com

Update a story

PATCH
/stories/{story_id}
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.

story_id
required
Story Id
string format: uuid
Media type application/json
StoryUpdate
object
title
Any of:
string
>= 1 characters <= 200 characters
summary
Any of:
string
<= 2000 characters
visibility
Any of:
StoryVisibility

Who may read a published story, besides its owner and admins.

string
Allowed values: private internal public
cover_asset_id
Any of:
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"
}

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).

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