Create a Story

You can set most of the fields that are available in the story object, below we only list the properties in the example and the possible required fields. Stories are not published by default. If you want to create a published story add the parameter publish with the value 1.

/spaces/:space_id/stories/

You can save any data in the story[content] attribute, and use it in the editor, as long as you follow these rules:

The story[content] property needs to be an object at the root level
Every object inside needs to have the property "component":"your_components_name"
Only nest components using arrays, except if you want to build a custom field type.
Every nested object which is a component or custom field type needs a _uid property.

This lets you import data and define the schema of your components afterwards in the interface where necessary.

Path Parameters

:space_id
required number

Numeric id of a space

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)
- 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)
- translated_slugs
  object[]
  
  Array of translated slug objects (if the app Translatable Slugs is installed)
- position
  number
  
  Numeric representation of the story's position in the folder
publish
number

Should the story be published immediately (set 1 to publish)
release_id
number

ID of the current release (can be requested with the from_release API parameter)

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)
- 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" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_OAUTH_TOKEN" \
  -d "{\"story\": {\"name\": \"Story Name\",\"slug\": \"story-name\",\"content\": {\"component\": \"page\",\"body\": []}},\"publish\": 1}"

Request

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

Request

$client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');

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

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

Request

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

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

client.post('/spaces/606/stories', payload)

Request

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

Request

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

request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"story\": {\"name\": \"Story Name\",\"slug\": \"story-name\",\"content\": {\"component\": \"page\",\"body\": []}},\"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\": \"Story Name\",\"slug\": \"story-name\",\"content\": {\"component\": \"page\",\"body\": []}},\"publish\": 1}".data(using: String.Encoding.utf8)!)
let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/stories")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)

request.method = "POST"
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"

querystring = {}

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

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

print(response.text)

Prev Retrieve Multiple Stories

Next Update a Story