Update a Story

This endpoint can be used for migrations, updates (e.g. if you changed your component structure), or bulk actions. If you want to publish your story immediately, add the parameter publish with the value 1 to the object.

To set alternate versions of a story, you can set the group_id equal to the group_id of the story (or stories) that should be the alternate(s). Two stories are alternates with each other when their group IDs are the same.

https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id

Path Parameters

:space_id
required number

Numeric ID of a space
:story_id
required number

The numeric id of story

Request Body Properties

story
The Story Object

A single story object
- name
  required string
  
  The complete name provided for the story
- parent_id
  number
  
  ID of the parent folder
- group_id
  string
  
  Group ID (UUID string), shared between stories defined as alternates
- sort_by_date
  string
  
  Date defined in the story's entry configuration (Format: YYYY-mm-dd)
- tag_list
  string[]
  
  Array of tag names
- is_folder
  boolean
  
  true if the instance constitutes a folder
- content
  object
  
  An object containing the field data associated with the specific story type's specific content structure. Also includes a component property with the story type's technical name.
- slug
  required string
  
  The slug specific for the story
- path
  string
  
  Value of the real path defined in the story's entry configuration (usually, this value is only required for Storyblok's Visual Editor)
- default_root
  string
  
  Component name which will be used as default content type for this folders entries
- disable_fe_editor
  boolean
  
  Is side by side editor disabled for all entries in folder
- is_startpage
  boolean
  
  true if the story is defined as root for the folder
- meta_data
  object
  
  Object to store non-editable data that is exclusively maintained with the Management API
- pinned
  boolean
  
  To pin the story in the toolbar
- first_published_at
  string
  
  First publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)
- position
  number
  
  Numeric representation of the story's position in the folder
group_id
string

Group ID (UUID string), shared between stories defined as alternates
force_update
string

If this is 1, the request can overwrite a locked story. Do note that if you do so, the user who was previously editing the story (which is why it was locked) will encounter a content conflict model.
release_id
number

Numeric ID of release (optional)
publish
number

Should the story be published immediately (set 1 to publish)
lang
string

Language code to publish the story individually (must be enabled in the space settings)

Response Properties

story
The Story Object

A single story object
- id
  number
  
  Numeric id of the story
- name
  string
  
  The complete name provided for the story
- parent_id
  number
  
  ID of the parent folder
- group_id
  string
  
  Group ID (UUID string), shared between stories defined as alternates
- alternates
  object[]
  
  An array containing objects that provide basic data of the stories defined as alternates of the current story
  - id
    number
    
    The numeric ID
  - name
    string
    
    The complete name provided for the story
  - slug
    string
    
    The slug specific for the story
  - published
    boolean
    
    true if a story has been published at least once (even if it is currently in draft)
  - full_slug
    string
    
    The full slug of the story, combining the parent folder(s) and the designated story slug
  - is_folder
    boolean
    
    true if the instance constitutes a folder
- created_at
  string
  
  Creation date (Format: yyyy-MM-dd'T'HH:mm:ssZ)
- deleted_at
  string
  
  Deleted date (Format: YYYY-mm-dd HH:MM)
- sort_by_date
  string
  
  Date defined in the story's entry configuration (Format: YYYY-mm-dd)
- tag_list
  string[]
  
  Array of tag names
- updated_at
  string
  
  Latest update date (Format: yyyy-MM-dd'T'HH:mm:ssZ)
- published_at
  string
  
  Latest publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)
- uuid
  string
  
  Generated UUID string
- is_folder
  boolean
  
  true if the instance constitutes a folder
- content
  object
  
  An object containing the field data associated with the specific story type's specific content structure. Also includes a component property with the story type's technical name.
- published
  boolean
  
  true if a story has been published at least once (even if it is currently in draft)
- slug
  string
  
  The slug specific for the story
- path
  string
  
  Value of the real path defined in the story's entry configuration (usually, this value is only required for Storyblok's Visual Editor)
- full_slug
  string
  
  The full slug of the story, combining the parent folder(s) and the designated story slug
- default_root
  string
  
  Component name which will be used as default content type for this folders entries
- disable_fe_editor
  boolean
  
  Is side by side editor disabled for all entries in folder
- parent
  object
  
  Essential parent information as object (resolved from parent_id)
- is_startpage
  boolean
  
  true if the story is defined as root for the folder
- unpublished_changes
  boolean
  
  Story has unpublished changes; saved but not published
- meta_data
  object
  
  Object to store non-editable data that is exclusively maintained with the Management API
- imported_at
  string
  
  Latest import date (Format: YYYY-mm-dd HH:MM)
- preview_token
  object
  
  Preview token
  - token
    string
    
    The token passed to the editor as preview parameter to allow edit mode verification
  - timestamp
    string
    
    Timestamp passed to the editor as preview parameter to allow edit mode verification
- pinned
  boolean
  
  To pin the story in the toolbar
- breadcrumbs
  object[]
  
  Array of resolved subset of link objects (one per path segment / parent)
  - id
    number
    
    Story ID
  - name
    string
    
    The complete name provided for the story
  - parent_id
    number
    
    ID of the parent folder
  - disable_fe_editor
    boolean
    
    Is side by side editor disabled for all entries in folder
  - path
    string
    
    Value of the real path defined in the story's entry configuration (usually, this value is only required for Storyblok's Visual Editor)
  - slug
    string
    
    The slug specific for the story
  - translated_slugs
    object[]
    
    Array of translated slug objects (if the app Translatable Slugs is installed)
- first_published_at
  string
  
  First publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)
- last_author
  object
  
  Last author
  - id
    number
    
    Last author user object numeric id
  - userid
    string
    
    Last author userid/username
  - friendly_name
    string
    
    Friendly name of last author
- last_author_id
  number
  
  Id of the last Author
- translated_slugs
  object[]
  
  Array of translated slug objects (if the app Translatable Slugs is installed)
  - story_id
    number
    
    ID of the story
  - lang
    string
    
    Language code of the current language (can be requested with the language API parameter)
  - slug
    string
    
    The slug specific for the story
  - name
    string
    
    The complete name provided for the story
  - published
    boolean
    
    true if a story has been published at least once (even if it is currently in draft)
- localized_paths
  object[]
  
  An array of translated path objects
  - path
    string
    
    Value of the real path defined in the story's entry configuration (usually, this value is only required for Storyblok's Visual Editor)
  - name
    string
    
    The complete name provided for the story
  - lang
    string
    
    Language code of the current language (can be requested with the language API parameter)
  - published
    boolean
    
    true if a story has been published at least once (even if it is currently in draft)
- position
  number
  
  Numeric representation of the story's position in the folder
- release_id
  number
  
  ID of the current release (can be requested with the from_release API parameter)
- scheduled_dates
  string
  
  Scheduled publishing date (Format: YYYY-mm-dd HH:MM)
- favourite_for_user_ids
  number[]
  
  Array of user IDs who have added the story in their favorites

Select a Language

Request

curl "https://mapi.storyblok.com/v1/spaces/606/stories/2141" \ 
  -X PUT \
  -H "Authorization: YOUR_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"story\": {\"name\": \"Updated Story Name\",\"slug\": \"story-name\",\"id\": 2141,\"content\": {\"component\": \"page\",\"body\": []}},\"force_update\": 1,\"publish\": 1}"

Request

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.put('/spaces/606/stories/2141', {
  "story": {
    "name": "Updated Story Name",
    "slug": "story-name",
    "id": 2141,
    "content": {
      "component": "page",
      "body": []
    }
  },
  "force_update": 1,
  "publish": 1
})
  .then(response => {
    console.log(response)
  }).catch(error => { 
    console.log(error)
  })

Request

$client = new \Storyblok\ManagementClient('YOUR_OAUTH_TOKEN');

$payload = [
  "story" =>  [
    "name" =>  "Updated Story Name",
    "slug" =>  "story-name",
    "id" =>  2141,
    "content" =>  [
      "component" =>  "page",
      "body" =>  []
    ]
  ],
  "force_update" =>  1,
  "publish" =>  1
];

$client->put('/spaces/606/stories/2141', $payload)->getBody();

Request

require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "story" =>  {
    "name" =>  "Updated Story Name",
    "slug" =>  "story-name",
    "id" =>  2141,
    "content" =>  {
      "component" =>  "page",
      "body" =>  []
    }
  },
  "force_update" =>  1,
  "publish" =>  1
}

client.put('/spaces/606/stories/2141', payload)

Request

HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/606/stories/2141")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"story\": {\"name\": \"Updated Story Name\",\"slug\": \"story-name\",\"id\": 2141,\"content\": {\"component\": \"page\",\"body\": []}},\"force_update\": 1,\"publish\": 1}")
  .asString();

Request

var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/stories/2141");
var request = new RestRequest(Method.PUT);

request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"story\": {\"name\": \"Updated Story Name\",\"slug\": \"story-name\",\"id\": 2141,\"content\": {\"component\": \"page\",\"body\": []}},\"force_update\": 1,\"publish\": 1}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

import Foundation

let headers = [
  "Content-Type": "application/json",
  "Authorization": "YOUR_OAUTH_TOKEN"
]

let postData = NSData(data: "{\"story\": {\"name\": \"Updated Story Name\",\"slug\": \"story-name\",\"id\": 2141,\"content\": {\"component\": \"page\",\"body\": []}},\"force_update\": 1,\"publish\": 1}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/stories/2141")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.method = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Request

import requests

url = "https://mapi.storyblok.com/v1/spaces/606/stories/2141"

querystring = {}

payload = "{\"story\": {\"name\": \"Updated Story Name\",\"slug\": \"story-name\",\"id\": 2141,\"content\": {\"component\": \"page\",\"body\": []}},\"force_update\": 1,\"publish\": 1}"
headers = {
  'Content-Type': "application/json",
  'Authorization': "YOUR_OAUTH_TOKEN"
}

response = requests.request("PUT", url, data=payload, headers=headers, params=querystring)

print(response.text)

Prev Create a Story

Next Delete a Story