Skip to main content

Management API Reference

The Storyblok Management API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP query parameters and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

The requests in the right sidebar are designed to work as is. The sample requests can be performed using your own API Authentication Token that you can obtain from your profile in the Storyblok application.

Edit this section on GitHub

API Libraries

Official libraries for the Storyblok Management API are available in several languages. Community-supported libraries are also available for additional languages.

Base URL

https://mapi.storyblok.com

Use Cases

The Management API should not be use to consume your information as it does not utilize our global CDN for your requests and can result in higher latencies. Please make sure to use the Content Delivery API instead.

Edit this section on GitHub
Use Case
Migration from your current data storage / CMS
Integration with 3rd party applications
Import and Export automation
Automatic translation workflows
Component versioning
Whitelabel integrations

Authentication

Authenticate your account by including your personal access token in API requests. The easiest way to get started is to create an OAuth2 token using the Storyblok app. Go to the My Account section at app.storyblok.com and click on “Generate new token”.

Your personal access token will grant anyone how obtains it with access to all associated spaces for your account, so make sure to never expose it on the client side or commit it in your source code. Use strategies like environment variables to secure your personal access token. If you have exposed your personal access token, make sure to delete it immediately from the My Account section.

Using an OAuth2 token, a username and password doesn’t need to be permanently stored and you can revoke access at any time.

Edit this section on GitHub

Example Request

curl -H "Authorization: YOUR_OAUTH_TOKEN" https://mapi.storyblok.com/

Example Request

// npm install storyblok-js-client
const StoryblokClient = require('storyblok-js-client')

// Initialize the client with the oauth token
const Storyblok = new StoryblokClient({
  oauthToken: 'YOUR_OAUTH_TOKEN'
})

Errors

Storyblok uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, content entry was not published but version requested was set to published, etc.). Codes in the 5xx range indicate an error with Storyblok's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., content entry was not found) include an error code that briefly explains the error reported.

Edit this section on GitHub

Http Status Code Summary

Code Description
200 - OK Everything worked as expected.
400 - Bad Request Wrong format was sent (eg. XML instead of JSON).
401 - Unauthorized No valid API key provided.
404 - Not Found The requested resource doesn't exist (perhaps due to not yet published content entries).
422 - Unprocessable Entity The request was unacceptable, often due to missing a required parameter.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on Storyblok's end. (These are rare.)

Rate Limit

The management api is rate limited to 3 requests per second for users on the free plan and 6 requests per second for other users.

Edit this section on GitHub
Plan Rate Limit
Free 3 per second
Basic 6 per second
Advanced 6 per second
Premium 6 per second
Enterprise Custom

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list stories and datasource_entries. These list API methods share a common structure, taking these two parameters: page, per_page.

The default per_page is set to 25 entries per page. You can increase this number to receive up to 100 entries per page. To go through different pages you can utilize the page parameter. The page parameter is a numeric value and uses 1 as default.

To allow a calculation of how many pages are available you can access the Total response header that you will receive after you made your first request. Access it and divide it with your per_page parameter to receive the highest possible page, otherwise you will receive an empty array as result.

Query Parameter Description
page Default: 1. Increase this to receive the next page of content entries
per_page Default: 25, Max for Stories: 100, Max for Datasource Entries: 1000 . Defines the number of content entries you will receive per page
Edit this section on GitHub

Example Request

https://api.storyblok.com/v1/spaces/(:space_id)/stories/?per_page=2&page=1

Example Response

{
  "stories": [
    { ... },
    { ... }
  ]
}

Example Response Headers

status: 200
per-page: 2
total: 3
...

Stories

The stories endpoint will let you manage all content entries of your Storyblok space. You can use it to import, export or modify content.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/stories/:story_id

The Story Object

This is an object representing your content entry. One Story object can be of a specific type, so called content types and is able to contain components. You define the fields and nestability of your content types to achieve your content structure. You can use this object to build up your entities when migrating or importing content.

Property Description
id Numeric id
uuid Generated uuid string
name The name you give this story
slug Gthe slug / path you give this story
full_slug Combined parent folder and current slug
path Given real path, used in the preview editor
content Your defined custom content object
release_id Id of your content stage (default: null)
lang Defined language (default: "default")
published Is story published (true/false)
unpublished_changes Story has unpublished changes; saved but not published (true/false)
position Position in folder
is_startpage Is startpage of current folder (true/false)
is_folder Is story a folder (true/false)
default_root Component name which will be used as default content type for this folders entries
disble_fe_editor Is side by side editor disabled for all entries in folder (true/false)
parent_id Parent story/folder numeric id
parent Essential parent information as object (resolved from parent_id)
group_id Alternates group id (uuid string)
alternates Array of resolved subset of link objects
tag_list Array of Tags (string only)
breadcrumbs Array of resolved subset of link objects (one per path segment / parent)
sort_by_date Legacy: Additional sorting date field (Format: YYYY-mm-dd)
meta_data JSON to add meta data that is not setting the story status to unpublished changes. Example: User ratings.
pinned To pin the story in the toolbar
preview_token[token] Token passed to the editor as preview parameter to allow editmode verification
preview_token[timestamp] Timestamp passed to the editor as preview parameter to allow editmode verification
last_author[id] Last author user object numeric id
last_author[userid] Last author userid/username
created_at Creation date (Format: YYYY-mm-dd HH:MM)
updated_at Latest update date (Format: YYYY-mm-dd HH:MM)
published_at Latest publishing date (Format: YYYY-mm-dd HH:MM)
first_published_at First publishing date (Format: YYYY-mm-dd HH:MM)
imported_at Latest import date (Format: YYYY-mm-dd HH:MM)
Edit this section on GitHub

Example Object 

{
  "story": {
    "id": 369689,
    "uuid": "039508c6-e9fa-42b5-b952-c7d96ab6099d",
    "name": "My third post",
    "slug": "my-third-post",
    "created_at": "2018-10-29T10:27:52.802Z",
    "updated_at": "2018-10-30T12:24:07.499Z",
    "published_at": "2018-08-07T09:40:13.802Z",
    "first_published_at": "2018-08-07T09:40:13.802Z",
    "imported_at": null,
    // group id defines the referenced alternates
    "group_id": "fb33b858-277f-4690-81fb-e0a080bd39ac",
    // resolved alternates by group_id
    "alternates": [],
    "sort_by_date": null,
    "tag_list": [],
    "is_folder": false,
    "content": {
      "_uid": "98cccd01-f807-4494-996d-c6b0de2045a5",
      "component": "your_content_type"
      // and fields you define yourself are in here
    },
    "path": null,
    "default_root": null,
    "disble_fe_editor": false,
    // parent folder id
    "parent_id": 369683,
    // resolved parent folder information
    "parent": {
      "id": 369683,
      "slug": "posts",
      "name": "Posts",
      "disble_fe_editor": true,
      "uuid": "dcfcc350-e63e-4232-8dcb-ba4b8e70799d"
    },
    "full_slug": "posts/my-third-post", // automatically generated
    // resolved full_slug parts
    "breadcrumbs": [{
      "id": 369683,
      "name": "Posts",
      "parent_id": 0,
      "disble_fe_editor": true
    }],
    "published": false,
    "unpublished_changes": true,
    "is_startpage": false,
    "meta_data": null,
    "pinned": false,
    "preview_token": {
      "token": "279395174a25be38b702f9ec90d08a960e1a5a84",
      "timestamp": "1545530576"
    },
    "last_author": {
      "id": 39821,
      "userid": "storyblok"
    }
  }
}

Retrieve one Story

Returns a single, fully loaded story object by providing a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/stories/369689" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/stories/369689', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/stories/369689')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/369689",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/stories/369689")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/stories/369689");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/stories/369689")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded story object as response.

Retrieve multiple Stories

Returns an array of story objects without content. Can be filtered with the parameters below and is paged.

Parameter Description
page Current page of stories
contain_component Filters by component in all levels of the content. Allows comma separated value for multiple components
search_term Filter by a term using full text search
sort_by Sort entries by specific attribute and order with content.YOUR_FIELD:asc and content.YOUR_FIELD:desc. Possible values are all root attributes of the entry (position and parent_position are special invisible attributes) and all fields of your content type inside content with a dot as seperator. Example: 'position:asc', 'parent_position:asc', 'content.your_custom_field:asc', 'created_at:desc'
pinned Filter by pinned stories if '1'
excluding_ids Exclude stories by ids (comma separated) from result
by_ids Filter by ids (comma separated)
by_uuids Filter by uuids (comma separated)
with_tag Filter by tag
folder_only Filter by folders only
story_only Filter by stories only
with_parent Filter by parent id
with_slug Filter by exact slug
starts_with Filter stories starting with a specific slug
in_trash Filter by items in the trash folder
search Filter by search term
filter_query Filter by specific attribute(s) of your content type. See content delivery api documentation.
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/stories/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/stories/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/stories/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/stories/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/stories/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/stories/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Example Request with search_term

curl "https://mapi.storyblok.com/v1/spaces/606/stories/?search_term=My%20fulltext%20search" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/stories/', {
  "search_term": "My fulltext search"
})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/stories/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/?search_term=My%20fulltext%20search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/stories/?search_term=My%20fulltext%20search")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/stories/?search_term=My%20fulltext%20search");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/stories/?search_term=My%20fulltext%20search")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {"search_term":"My fulltext search"}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Example Request with by_uuids

curl "https://mapi.storyblok.com/v1/spaces/606/stories/?by_uuids=fb3afwa58-277f-4690-81fb-e0a080bd39ac,81fb81fb-e9fa-42b5-b952-c7d96ab6099d" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/stories/', {
  "by_uuids": "fb3afwa58-277f-4690-81fb-e0a080bd39ac,81fb81fb-e9fa-42b5-b952-c7d96ab6099d"
})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/stories/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/?by_uuids=fb3afwa58-277f-4690-81fb-e0a080bd39ac,81fb81fb-e9fa-42b5-b952-c7d96ab6099d",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/stories/?by_uuids=fb3afwa58-277f-4690-81fb-e0a080bd39ac,81fb81fb-e9fa-42b5-b952-c7d96ab6099d")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/stories/?by_uuids=fb3afwa58-277f-4690-81fb-e0a080bd39ac,81fb81fb-e9fa-42b5-b952-c7d96ab6099d");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/stories/?by_uuids=fb3afwa58-277f-4690-81fb-e0a080bd39ac,81fb81fb-e9fa-42b5-b952-c7d96ab6099d")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {"by_uuids":"fb3afwa58-277f-4690-81fb-e0a080bd39ac,81fb81fb-e9fa-42b5-b952-c7d96ab6099d"}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of story objects without content as response.

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.

Property Description
story Your full story object
story[name] Name of the story is required
story[slug] Slug is required; Used to identify the story (can not include /create stories with is_folder and required path segments and parent_id link instead)
story[content] Object structure for your content
story[default_root] (required*) Default content type/root component. (*Required if is_folder is true)
publish Should the story be published immediately (set 1 to publish)

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

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

Edit this section on GitHub

Example 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}"
// use the universal js client to perform the request
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)
})
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)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"story\":{\"name\":\"Story Name\",\"slug\":\"story-name\",\"content\":{\"component\":\"page\",\"body\":[]}},\"publish\":1}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
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();
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);
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.httpMethod = "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()
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 = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded story object as a response.

Update a Story

Can be used to build migrations, updates if you changed your component structure, or if you only need to do a bulk action on all your content items.

Property Description
story Your full story object
force_update If '1' it will overwrite a locked story
Edit this section on GitHub

Example 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\":\"Story Name\",\"slug\":\"story-name\",\"id\":2141,\"content\":{\"component\":\"page\",\"body\":[]}},\"force_update\":1}"
// use the universal js client to perform the request
Storyblok.put('spaces/606/stories/2141', {
  "story": {
    "name": "Story Name",
    "slug": "story-name",
    "id": 2141,
    "content": {
      "component": "page",
      "body": []
    }
  },
  "force_update": 1
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

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

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

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/2141",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"story\":{\"name\":\"Story Name\",\"slug\":\"story-name\",\"id\":2141,\"content\":{\"component\":\"page\",\"body\":[]}},\"force_update\":1}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
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\":\"Story Name\",\"slug\":\"story-name\",\"id\":2141,\"content\":{\"component\":\"page\",\"body\":[]}},\"force_update\":1}")
  .asString();
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\":\"Story Name\",\"slug\":\"story-name\",\"id\":2141,\"content\":{\"component\":\"page\",\"body\":[]}},\"force_update\":1}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"story\":{\"name\":\"Story Name\",\"slug\":\"story-name\",\"id\":2141,\"content\":{\"component\":\"page\",\"body\":[]}},\"force_update\":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.httpMethod = "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()
import requests

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

querystring = {}

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

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

print(response.text)

You will receive a fully loaded story object as response.

Delete a Story

Delete a content entry by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/stories/2141" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/stories/2141').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/stories/2141')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/2141",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/stories/2141")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/stories/2141");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

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

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()
import requests

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

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Internationalization for Stories

If you use our field level translations functionality, you can provide the values for the translations/languages within the same content object by appending __i18n__ followed by the language code. Make sure to have the component field option translateable to true.

Get a full list of our languages codes on Github.

Edit this section on GitHub

Example 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\":\"My First Article\",\"slug\":\"first-post\",\"content\":{\"component\":\"post\",\"headline\":\"This is awesome!\",\"headline__i18n__de\":\"Das ist toll!\"}},\"publish\":1}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/stories/', {
  "story": {
    "name": "My First Article",
    "slug": "first-post",
    "content": {
      "component": "post",
      "headline": "This is awesome!",
      "headline__i18n__de": "Das ist toll!"
    }
  },
  "publish": 1
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "story" =>  {
    "name" =>  "My First Article",
    "slug" =>  "first-post",
    "content" =>  {
      "component" =>  "post",
      "headline" =>  "This is awesome!",
      "headline__i18n__de" =>  "Das ist toll!"
    }
  },
  "publish" =>  1
}

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

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"story\":{\"name\":\"My First Article\",\"slug\":\"first-post\",\"content\":{\"component\":\"post\",\"headline\":\"This is awesome!\",\"headline__i18n__de\":\"Das ist toll!\"}},\"publish\":1}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
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\":\"My First Article\",\"slug\":\"first-post\",\"content\":{\"component\":\"post\",\"headline\":\"This is awesome!\",\"headline__i18n__de\":\"Das ist toll!\"}},\"publish\":1}")
  .asString();
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\":\"My First Article\",\"slug\":\"first-post\",\"content\":{\"component\":\"post\",\"headline\":\"This is awesome!\",\"headline__i18n__de\":\"Das ist toll!\"}},\"publish\":1}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"story\":{\"name\":\"My First Article\",\"slug\":\"first-post\",\"content\":{\"component\":\"post\",\"headline\":\"This is awesome!\",\"headline__i18n__de\":\"Das ist toll!\"}},\"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.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"story\":{\"name\":\"My First Article\",\"slug\":\"first-post\",\"content\":{\"component\":\"post\",\"headline\":\"This is awesome!\",\"headline__i18n__de\":\"Das ist toll!\"}},\"publish\":1}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Publish a Story

Publishing a story besides using the publish property via creation, can be done by using a GET request for each story you want to publish.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/stories/2141/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/stories/2141/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/stories/2141/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/stories/2141/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/stories/2141/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/stories/2141/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

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

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Components

A component is a standalone entity that is meaningful in its own right. While components (or bloks) can be nested in each other, semantically they remain equal. Each component is a small piece of your data structure which can be filled with content or nested by your content editor. One component can consist of as many field types as required.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/components/:component_id

The Component Object

Property Description
id Numeric Unique ID
name Technical name used for component property in entries
display_name Name that will be used in the editor interface
created_at Creation date (Format: YYYY-mm-dd HH:MM)
image URL to the preview image, if uploaded
preview Define the field that should be used for preview in the interface
is_root Component should be usable as a Content Type
is_nestable Component should be insertable in blocks field type fields
all_presets Array of presets for this component
real_name Duplicated technical name, used for internal tasks
Edit this section on GitHub

Example Object

{
  "component": {
    "id": 214123,
    "name": "post",
    "display_name": "Post",
    "created_at": "2018-12-28T14:54:01.423Z",
    "schema": {
      // definition of fields (schema) for this component
      "title": {
        "type": "text",
        "pos": 0
      },
      "description": {
        "type": "text",
        "pos": 1
      },
      ...
    },
    "image": null,
    "preview_field": null,
    "is_root": true,
    "is_nestable": true,
    "all_presets": [],
    "preset_id": null,
    "real_name": "post"
  },
  "update_content": true
}

The Component Field

Not every property will be used for every field type; some may only effect specific types.

Property Description
id Numeric Unique ID
type The type of your field
pos Position of field in component
translateable Can field be translated; Default: false
required Is field required; Default: false
regex Client Regex validation for the field
description Description shown in the editor interface
default_value Default value for the field; Can be an escaped JSON object
can_sync Advanced usage to sync with field in preview; Default: false
preview_field Is used as instance preview field below component name in bloks types
no_translate Boolean; Should be excluded in translation export
rtl Boolean; Enable global RTL for this field
Only for type: markdown, text, textarea
rich_markdown Enable rich markdown view by default (true/false);
Only for type: markdown
keys Array of field keys to include in this section;
Only for type: section
field_type Name of the custom field type plugin;
Only for type: custom
source Possible values: undefined: Self; internal_stories: Stories; internal: Datasource; external: API Endpoint in Datasource Entries Array Format;
Only for type: options, option, custom;
use_uuid Default: true; available in option and source=internal_stories
folder_slug Filter on selectable stories path; Effects editor only if source=internal_stories; In case you have a multi-language folder structure you can add the '{0}' placeholder and the path will be adapted dynamically. Examples: *"{0}/categories/", *{0}/{1}/categories/
datasource_slug Define selectable datasources string; Effects editor only if source=internal
external_datasource Define external datasource JSON Url; Effects editor only if source=external
options Array of datasource entries [{name:"", value:""}]; Effects editor only if source=undefined
image_crop Activate force crop for images: (true/false);
Only for type: image
keep_image_size Keep original size: (true/false);
Only for type: image
image_width Define width in px or width ratio if keep_image_size is enabled;
Only for type: image
image_height Define height in px or height ratio if keep_image_size is enabled;
Only for type: image
asset_folder_id Default asset folder numeric id to store uploaded image of that field;
Only for type: image
add_https Prepends https: to stop usage of relative protocol;
Only for type: image, file
restrict_components Activate restriction nestable component option; Default: false;
Only for type: bloks
maximum Maximum amount of added bloks in this blok field;
Only for type: bloks
restrict_content_types Activate restriction content type option;
Only for type: multilink
component_whitelist Array of component/content type names: ["post","page","product"];
Only for type: bloks, multilink
disable_time Disables time selection from date picker; Default: false;
Only for type: datetime
max_length Set the max length of the input string;
Only for type: text, textarea, markdown
Edit this section on GitHub

Example Object

// name of the field as key eg. "field key" in schema property in your component
"title": {
  "type": "text",
  "pos": 0,
  "translatable": true,
  "required": true,
  "regex": "",
  "description": "Description for the field",
  "display_name": "",
  "default_value": "",
  "can_sync": false,
  "rtl": false,
  "no_translate": false
}

Possible field types

Field Type Description
bloks Blocks; a field to interleave other components in your current one
text Text; a text field
textarea Textarea; a text area
markdown Markdown; write markdown with a text area and additional formatting options
number Number; a number field
datetime Date/Time; a date- and time picker
boolean Boolean; a checkbox - true/false
options Multi-Options; a list of checkboxes
option Single-Option; a single dropdown
image Image; a upload field for a single image with cropping possibilities
file File; a upload field for a single file
multiasset Multi-Assets; a upload field for a multiple files
multilink Link; an input field for internal linking to other stories
section Group; no input possibility - allows you to group fields in sections
custom Plugin; Extend the editor yourself with a color picker or similar - Check out: Creating a Storyblok field type plugin
Edit this section on GitHub

Example Object

"field_key": {
  ...
  "type": "text", // <-- field type
  ...
}

Retrieve one Component

Returns a single, fully loaded component object by providing a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/components/4123" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/components/4123', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/components/4123')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/components/4123",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/components/4123")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/components/4123");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/components/4123")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/components/4123"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded component object as response.

Retrieve multiple Components

Returns an array of component objects. This endpoint is paged.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/components/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/components/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/components/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/components/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/components/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/components/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/components/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of component objects as response.

Create a Component

You can set most of the fields that are available in the component object, below we only list the properties in the example and possible required fields.

Property Description
component Your full component object
component[name] The component name is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/656/components/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"component\":{\"name\":\"teaser\",\"display_name\":\"Teaser\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1}},\"is_root\":false,\"is_nestable\":true}}"
// use the universal js client to perform the request
Storyblok.post('spaces/656/components/', {
  "component": {
    "name": "teaser",
    "display_name": "Teaser",
    "schema": {
      "title": {
        "type": "text",
        "pos": 0
      },
      "image": {
        "type": "image",
        "pos": 1
      }
    },
    "is_root": false,
    "is_nestable": true
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "component" =>  {
    "name" =>  "teaser",
    "display_name" =>  "Teaser",
    "schema" =>  {
      "title" =>  {
        "type" =>  "text",
        "pos" =>  0
      },
      "image" =>  {
        "type" =>  "image",
        "pos" =>  1
      }
    },
    "is_root" =>  false,
    "is_nestable" =>  true
  }
}

client.post('spaces/656/components/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/656/components/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"component\":{\"name\":\"teaser\",\"display_name\":\"Teaser\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1}},\"is_root\":false,\"is_nestable\":true}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/656/components/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"component\":{\"name\":\"teaser\",\"display_name\":\"Teaser\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1}},\"is_root\":false,\"is_nestable\":true}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/components/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"component\":{\"name\":\"teaser\",\"display_name\":\"Teaser\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1}},\"is_root\":false,\"is_nestable\":true}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"component\":{\"name\":\"teaser\",\"display_name\":\"Teaser\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1}},\"is_root\":false,\"is_nestable\":true}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/656/components/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/656/components/"

querystring = {}

payload = "{\"component\":{\"name\":\"teaser\",\"display_name\":\"Teaser\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1}},\"is_root\":false,\"is_nestable\":true}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded component object as response.

Update a Component

Send the component object with updated values to our backend using the PUT method. An update on component will not take over already inserted values, make sure to also update your stories that contain this component.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/656/components/4123" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"component\":{\"name\":\"teaser\",\"id\":4123,\"display_name\":\"Teaser Updated\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1},\"description\":{\"type\":\"textarea\",\"pos\":2}},\"is_root\":false,\"is_nestable\":true}}"
// use the universal js client to perform the request
Storyblok.put('spaces/656/components/4123', {
  "component": {
    "name": "teaser",
    "id": 4123,
    "display_name": "Teaser Updated",
    "schema": {
      "title": {
        "type": "text",
        "pos": 0
      },
      "image": {
        "type": "image",
        "pos": 1
      },
      "description": {
        "type": "textarea",
        "pos": 2
      }
    },
    "is_root": false,
    "is_nestable": true
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "component" =>  {
    "name" =>  "teaser",
    "id" =>  4123,
    "display_name" =>  "Teaser Updated",
    "schema" =>  {
      "title" =>  {
        "type" =>  "text",
        "pos" =>  0
      },
      "image" =>  {
        "type" =>  "image",
        "pos" =>  1
      },
      "description" =>  {
        "type" =>  "textarea",
        "pos" =>  2
      }
    },
    "is_root" =>  false,
    "is_nestable" =>  true
  }
}

client.put('spaces/656/components/4123', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/656/components/4123",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"component\":{\"name\":\"teaser\",\"id\":4123,\"display_name\":\"Teaser Updated\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1},\"description\":{\"type\":\"textarea\",\"pos\":2}},\"is_root\":false,\"is_nestable\":true}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/656/components/4123")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"component\":{\"name\":\"teaser\",\"id\":4123,\"display_name\":\"Teaser Updated\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1},\"description\":{\"type\":\"textarea\",\"pos\":2}},\"is_root\":false,\"is_nestable\":true}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/components/4123");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"component\":{\"name\":\"teaser\",\"id\":4123,\"display_name\":\"Teaser Updated\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1},\"description\":{\"type\":\"textarea\",\"pos\":2}},\"is_root\":false,\"is_nestable\":true}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"component\":{\"name\":\"teaser\",\"id\":4123,\"display_name\":\"Teaser Updated\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1},\"description\":{\"type\":\"textarea\",\"pos\":2}},\"is_root\":false,\"is_nestable\":true}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/656/components/4123")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/656/components/4123"

querystring = {}

payload = "{\"component\":{\"name\":\"teaser\",\"id\":4123,\"display_name\":\"Teaser Updated\",\"schema\":{\"title\":{\"type\":\"text\",\"pos\":0},\"image\":{\"type\":\"image\",\"pos\":1},\"description\":{\"type\":\"textarea\",\"pos\":2}},\"is_root\":false,\"is_nestable\":true}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded, updated component object as response.

Delete a Component

Delete any component using its numeric id. Already used components will still stay in place but will show up with no schema definition so your inserted values won't be removed. You can use the update stories to migrate your content to other or new components.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/components/4123" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/components/4123').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/components/4123')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/components/4123",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/components/4123")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/components/4123");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/components/4123")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/components/4123"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Assets

Assets like images, videos and documents are kept in the CDN as long as possible and will rarely hit the origin server. Each asset object references one of those uploaded images, videos and documents.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/assets/:asset_id

The Asset Object

Property Description
id Numeric Unique ID
filename Full path of the asset, including the file name
space_id Space ID in which the asset is connected
created_at Creation date (Format: YYYY-mm-dd HH:MM)
updated_at Latest update date (Format: YYYY-mm-dd HH:MM)
deleted_at Deleted date (Format: YYYY-mm-dd HH:MM)
file File Object
asset_folder_id Id of the folder containing this asset
short_filename The file name of the asset
content_type The MIME type of the asset
content_length The content length in bytes
Edit this section on GitHub

Example Object

{
  "id": 14,
  "filename": "/f/616/SIZE/UNIQUEIDENTIFIER/your_filename.jpg",
  "space_id": 616,
  "created_at": "2018-11-10T15:33:00.578Z",
  "updated_at": "2018-11-10T15:33:00.578Z",
  "file": {
    "url": null
  },
  "asset_folder_id": null,
  "deleted_at": null,
  "short_filename": "your_filename.jpg",
  "content_type": "image/jpeg",
  "content_length": 12303
}

Signed Response Object

After creating an asset entry using a POST request you will receive a response object with all information needed to finally upload your asset. The second request after the creation of the asset entry will need all information in fields appended to your application/x-www-form-urlencoded request besides the actual file input. See the demo on how to upload an asset.

Edit this section on GitHub

Example Object

{
  "pretty_url": "//a-example.storyblok.com/f/606/e5990a3595/your_file.jpg",
  "public_url": "https://s3.amazonaws.com/a-example.storyblok.com/f/606/e5990a3595/your_file.jpg",
  "fields": {
    "key": "f/606/e5990a3595/your_file.jpg",
    "acl": "public-read",
    "Expires": "Sun, 10 Nov 2019 15:33:00 GMT",
    "Cache-Control": "public; max-age=31536000",
    "Content-Type": "image/jpeg",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAxOC0xMS0xMFQxNTo...ei1hbGdvcml0aG0iOiJBV1M0LUhNQUM...LWFtei1kYXRlIjoiMjAxODExMTBUMTUzMzAwWiJ9XX0=",
    "x-amz-credential": "AKIAIU627EN23A/20181110/s3/aws4_request",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-date": "20181110T153300Z",
    "x-amz-signature": "aaedd72b54636662b137b7648b54bdb47ee3b1dd28173313647930e625c8"
  },
  "post_url": "https://s3.amazonaws.com/a-example.storyblok.com"
}

Retrieve one Asset

Returns a single asset object by providing a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/assets/14" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/assets/14', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/assets/14')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/assets/14",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/assets/14")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/assets/14");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/assets/14")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/assets/14"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an asset object as response.

Retrieve multiple Assets

Returns an array of asset objects. This endpoint is paged.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/assets/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/assets/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/assets/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/assets/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/assets/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/assets/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/assets/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of asset objects as response.

Upload Asset

Uploading assets in Storyblok is a two step process. First you need to sign the asset you want to upload. Then you need to post the image as form data to our Amazon S3 bucket. Uploaded files will have parameterized names; Every dot "." (except the last one) will be replaced with underscore "_";

Here you can find an example using Node.js on Github.

Edit this section on GitHub

1) Start by requesting a signed upload URL and parameter

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/assets/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"filename\":\"your_file.jpg\",\"size\":\"400x500\"}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/assets/', {
  "filename": "your_file.jpg",
  "size": "400x500"
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "filename" =>  "your_file.jpg",
  "size" =>  "400x500"
}

client.post('spaces/606/assets/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/assets/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"filename\":\"your_file.jpg\",\"size\":\"400x500\"}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/assets/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"filename\":\"your_file.jpg\",\"size\":\"400x500\"}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/assets/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"filename\":\"your_file.jpg\",\"size\":\"400x500\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"filename\":\"your_file.jpg\",\"size\":\"400x500\"}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/assets/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"filename\":\"your_file.jpg\",\"size\":\"400x500\"}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

2) Use the received signed response object to upload your file (example uses Node.js): 

const FormData = require('form-data')
const fs = require('fs')

const file = '/path_to/your_file.jpg'
const fileUpload = (signed_response_object, success, failed) => {
  let form = new FormData()
  // apply all fields from the signed response object to the second request
  for (let key in signed_response_object.fields) {
    form.append(key, signed_response_object.fields[key])
  }
  // also append the file read stream
  form.append('file', fs.createReadStream(file))
  // submit your form
  form.submit(signed_response_object.post_url, (err, res) => {
    if (err) throw err
    console.log('https://a.storyblok.com/' + signed_response_object.fields.key + ' uploaded!')
  })
}

Delete an Asset

Delete an asset by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/assets/14" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/assets/14').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/assets/14')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/assets/14",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/assets/14")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/assets/14");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/assets/14")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/assets/14"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Asset Folders

Asset folder allow you to group your assets. Besides the overall root folder you can define nested folder structures.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/asset_folders/:asset_folder_id

The Asset Folder Object

Property Description
id Numeric Unique ID
name Display name of your asset folder
parent_id Parent asset folder id
Edit this section on GitHub

Example Object

{
  "asset_folder": {
    "id": 41,
    "name": "Header Images",
    "parent_id": null
  }
}

Retrieve one Asset Folder

Returns a single, asset folder object by providing a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/asset_folders/41', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/asset_folders/41')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/asset_folders/41")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/asset_folders/41");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded asset folder object as response.

Retrieve multiple Asset Folders

Returns an array of asset folder objects.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/asset_folders/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/asset_folders/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/asset_folders/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/asset_folders/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/asset_folders/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/asset_folders/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/asset_folders/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of asset folder objects as response.

Create an Asset Folder

Property Description
asset_folder Your full asset folder object
asset_folder[name] Name is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/asset_folders/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"asset_folder\":{\"name\":\"Header Images\"}}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/asset_folders/', {
  "asset_folder": {
    "name": "Header Images"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "asset_folder" =>  {
    "name" =>  "Header Images"
  }
}

client.post('spaces/606/asset_folders/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/asset_folders/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"asset_folder\":{\"name\":\"Header Images\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/asset_folders/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"asset_folder\":{\"name\":\"Header Images\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/asset_folders/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"asset_folder\":{\"name\":\"Header Images\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"asset_folder\":{\"name\":\"Header Images\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/asset_folders/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"asset_folder\":{\"name\":\"Header Images\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an asset folder object as response.

Update an Asset Folder

Property Description
asset_folder Your full asset folder object
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"asset_folder\":{\"id\":41,\"name\":\"Update Header Images\"}}"
// use the universal js client to perform the request
Storyblok.put('spaces/606/asset_folders/41', {
  "asset_folder": {
    "id": 41,
    "name": "Update Header Images"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "asset_folder" =>  {
    "id" =>  41,
    "name" =>  "Update Header Images"
  }
}

client.put('spaces/606/asset_folders/41', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"asset_folder\":{\"id\":41,\"name\":\"Update Header Images\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/606/asset_folders/41")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"asset_folder\":{\"id\":41,\"name\":\"Update Header Images\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/asset_folders/41");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"asset_folder\":{\"id\":41,\"name\":\"Update Header Images\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"asset_folder\":{\"id\":41,\"name\":\"Update Header Images\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41"

querystring = {}

payload = "{\"asset_folder\":{\"id\":41,\"name\":\"Update Header Images\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an asset folder object as response.

Delete an Asset Folder

Delete an asset folder by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/asset_folders/41').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/asset_folders/41')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/asset_folders/41")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/asset_folders/41");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/asset_folders/41"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Datasources

A datasource is a collection of datasource entries with a specific name and slug. Each datasource entry is a collection of key-value pairs (KVP), so called datasource entries. Those key-value pairs can be used for a single choice, multiple choice options and as well directly through our API to use them for multi-language labels, categories, or anything similar.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/datasources/:datasource_id

The Datasource Object

Property Description
id Numeric Unique ID, used to reference datasource entries
name The key which will be used to resolve the given value
slug The slug used to request the datasource via API
dimensions List of defined dimensions for this datasource
Edit this section on GitHub

Example Object

{
  "datasource": {
    "id": 91,
    "name": "Labels for Website",
    "slug": "labels",
    "dimensions": [

    ]
  }
}

Retrieve one Datasource

Returns a single datasource object with a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasources/91" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/datasources/91', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/datasources/91')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasources/91",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/datasources/91")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasources/91");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasources/91")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/datasources/91"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a datasource object as response.

Retrieve multiple Datasources

Returns an array of datasource objects. This endpoint is paged and can be filtered by a datasource id or slug. The dimension parameter allows you to have the dimension value filled with the according data.

Parameter Description
datasource_id Provide the numeric id of a datasource
datasource_slug Provide the slug of a datasource
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasources/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/datasources/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/datasources/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasources/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/datasources/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasources/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasources/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of datasource objects as response.

Create a Datasource Entry

Property Description
datasource Your full datasource object
datasource[name] Name is required
datasource[slug] Slug is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasources/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"datasource\":{\"name\":\"Labels for Website\",\"slug\":\"labels\"}}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/datasources/', {
  "datasource": {
    "name": "Labels for Website",
    "slug": "labels"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "datasource" =>  {
    "name" =>  "Labels for Website",
    "slug" =>  "labels"
  }
}

client.post('spaces/606/datasources/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasources/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"datasource\":{\"name\":\"Labels for Website\",\"slug\":\"labels\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/datasources/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"datasource\":{\"name\":\"Labels for Website\",\"slug\":\"labels\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasources/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"datasource\":{\"name\":\"Labels for Website\",\"slug\":\"labels\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"datasource\":{\"name\":\"Labels for Website\",\"slug\":\"labels\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasources/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"datasource\":{\"name\":\"Labels for Website\",\"slug\":\"labels\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a datasource object as response.

Update a Datasource Entry

Property Description
datasource A datasource object
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasources/91" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"datasource\":{\"id\":91,\"name\":\"Labels for Website\",\"slug\":\"labels_for_website\"}}"
// use the universal js client to perform the request
Storyblok.put('spaces/606/datasources/91', {
  "datasource": {
    "id": 91,
    "name": "Labels for Website",
    "slug": "labels_for_website"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "datasource" =>  {
    "id" =>  91,
    "name" =>  "Labels for Website",
    "slug" =>  "labels_for_website"
  }
}

client.put('spaces/606/datasources/91', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasources/91",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"datasource\":{\"id\":91,\"name\":\"Labels for Website\",\"slug\":\"labels_for_website\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/606/datasources/91")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"datasource\":{\"id\":91,\"name\":\"Labels for Website\",\"slug\":\"labels_for_website\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasources/91");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"datasource\":{\"id\":91,\"name\":\"Labels for Website\",\"slug\":\"labels_for_website\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"datasource\":{\"id\":91,\"name\":\"Labels for Website\",\"slug\":\"labels_for_website\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasources/91")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/datasources/91"

querystring = {}

payload = "{\"datasource\":{\"id\":91,\"name\":\"Labels for Website\",\"slug\":\"labels_for_website\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a datasource object as response.

Delete a Datasource

Delete a datasource by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasources/91" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/datasources/91').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/datasources/91')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasources/91",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/datasources/91")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasources/91");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasources/91")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/datasources/91"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Datasource Entries

The actual KEY/VALUE pair object a datasource consists of. One specific datasource entry is a set of two linked data items: a key, which is a unique identifier for the item of data scoped in the data source, and the value, which is the data that is identified.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/datasource_entries/:datasource_entry_id

The Datasource Entry Object

Property Description
id Numeric Unique ID
name The key which will be used to resolve the given value
value The actual value for the provided key
datasource_id Numeric ID of connected datasource
Edit this section on GitHub

Example Object

{ 
  "datasource_entry" : {
    "id": 52,
    "name": "newsletter_text",
    "value": "Subscribe to our newsletter to make sure you don’t miss anything.",
    "datasource_id": ""
  }
}

Retrieve one Datasource Entry

Returns a single datasource entry object with a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/datasource_entries/52', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/datasource_entries/52')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a datasource entry object as response.

Retrieve multiple Datasource Entries

Returns an array of datasource entry objects. This endpoint is paged and can be filtered by a datasource id or slug. The dimension parameter allows you to have the dimension value filled with the according data.

Parameter Description
datasource_id Provide the numeric id of a datasource
datasource_slug Provide the slug of a datasource
dimension Provide dimension to receive the dimension_value filled
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/?datasource_id=124" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/datasource_entries/', {
  "datasource_id": 124
})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/datasource_entries/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/?datasource_id=124",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/?datasource_id=124")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/?datasource_id=124");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/?datasource_id=124")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {"datasource_id":124}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of datasource entry objects as response.

Create a Datasource Entry

Property Description
datasource_entry Your full datasource entry object
datasource_entry[name] Name is required
datasource_entry[value] Value is required
datasource_entry[datasource_id] Datasource Id is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"datasource_entry\":{\"name\":\"newsletter_text\",\"value\":\"Subscribe to our newsletter to make sure you don’t miss anything.\",\"datasource_id\":12345}}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/datasource_entries/', {
  "datasource_entry": {
    "name": "newsletter_text",
    "value": "Subscribe to our newsletter to make sure you don’t miss anything.",
    "datasource_id": 12345
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "datasource_entry" =>  {
    "name" =>  "newsletter_text",
    "value" =>  "Subscribe to our newsletter to make sure you don’t miss anything.",
    "datasource_id" =>  12345
  }
}

client.post('spaces/606/datasource_entries/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"datasource_entry\":{\"name\":\"newsletter_text\",\"value\":\"Subscribe to our newsletter to make sure you don’t miss anything.\",\"datasource_id\":12345}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"datasource_entry\":{\"name\":\"newsletter_text\",\"value\":\"Subscribe to our newsletter to make sure you don’t miss anything.\",\"datasource_id\":12345}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"datasource_entry\":{\"name\":\"newsletter_text\",\"value\":\"Subscribe to our newsletter to make sure you don’t miss anything.\",\"datasource_id\":12345}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"datasource_entry\":{\"name\":\"newsletter_text\",\"value\":\"Subscribe to our newsletter to make sure you don’t miss anything.\",\"datasource_id\":12345}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"datasource_entry\":{\"name\":\"newsletter_text\",\"value\":\"Subscribe to our newsletter to make sure you don’t miss anything.\",\"datasource_id\":12345}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a datasource entry object as response.

Update a Datasource Entry

Property Description
datasource_entry Your full datasource entry object
datasource_entry[name] Name is required
datasource_entry[value] Value is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"datasource_entry\":{\"id\":52,\"name\":\"newsletter_text\",\"value\":\"Subscribe to our updated newsletter to make sure you don’t miss anything.\"}}"
// use the universal js client to perform the request
Storyblok.put('spaces/606/datasource_entries/52', {
  "datasource_entry": {
    "id": 52,
    "name": "newsletter_text",
    "value": "Subscribe to our updated newsletter to make sure you don’t miss anything."
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "datasource_entry" =>  {
    "id" =>  52,
    "name" =>  "newsletter_text",
    "value" =>  "Subscribe to our updated newsletter to make sure you don’t miss anything."
  }
}

client.put('spaces/606/datasource_entries/52', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"datasource_entry\":{\"id\":52,\"name\":\"newsletter_text\",\"value\":\"Subscribe to our updated newsletter to make sure you don’t miss anything.\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"datasource_entry\":{\"id\":52,\"name\":\"newsletter_text\",\"value\":\"Subscribe to our updated newsletter to make sure you don’t miss anything.\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"datasource_entry\":{\"id\":52,\"name\":\"newsletter_text\",\"value\":\"Subscribe to our updated newsletter to make sure you don’t miss anything.\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"datasource_entry\":{\"id\":52,\"name\":\"newsletter_text\",\"value\":\"Subscribe to our updated newsletter to make sure you don’t miss anything.\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52"

querystring = {}

payload = "{\"datasource_entry\":{\"id\":52,\"name\":\"newsletter_text\",\"value\":\"Subscribe to our updated newsletter to make sure you don’t miss anything.\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a datasource entry object as response.

Delete a Datasource Entry

Delete a datasource entry by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/datasource_entries/52').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/datasource_entries/52')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/datasource_entries/52"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Spaces

A space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, datasources, assets, environments, domains, collaborators, and permissions.

If you want to launch several websites or apps, the best way to go is to create a separate space for each project.

If your goal is to deliver the same content to multiple platforms (a common set would be the web, iOS, and an Android app), then you should use one space and create multiple API keys to deliver the content. You can find the API keys in the space dashboard.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id

The Space Object

The space object contains all information of one of your accounts spaces. Some of the properties are read only other can be managed by the API. Properties that you are able to change or use during creation can be found in the specifici sections.

Example Space Options

...
"options": {
  "branch_deployed_hook": "", // Your webhook endpoint for branch deployments
  "s3_bucket": "storyblok-backup", // Your S3 bucket name
  "aws_arn": "arn:aws:iam::12312412:role/StoryblokRemote49122",
  "backup_frequency": "daily", 
  "languages": [ { "code": "de", "name": "German" } ]
}

Example Space Billing Address

...
"billing_address": {
  "tax_number": "ATU72706128", // Your VAT number
  "order_number": "Your custom order number",
  "company": "Storyblok GmbH",
  "email": "da@storyblok.com", 
  "name": "Ing. Dominik Angerer", 
  "address_city": "Linz", 
  "address_country": "Austria", 
  "address_iso_country": "AT",
  "address_line1": "Peter-Behrens-Platz 1", 
  "address_zip": "4020", 
}
Edit this section on GitHub

Example Object

{
  "space": {
    "name": "Example Space",
    "domain": "https://example.storyblok.com",
    "uniq_domain": null,
    "plan": "starter",
    "plan_level": 0,
    "limits": { },
    "created_at": "2018-11-10T15:33:18.402Z",
    "id": 680,
    "role": "admin",
    "owner_id": 1114,
    "story_published_hook": null,
    "environments": null,
    "stories_count": 1,
    "parent_id": null,
    "assets_count": 0,
    "searchblok_id": null,
    "duplicatable": null,
    "request_count_today": 0,
    "api_requests": 1000,
    "exceeded_requests": 0,
    "billing_address": { 
      // billing infromation
    },
    "routes": [ ],
    "euid": null,
    "trial": true,
    "default_root": "page",
    "has_slack_webhook": false,
    "api_logs_per_month": [ ],
    "first_token": "8IE7MzYCzw5d7KLckDa38Att",
    "has_pending_tasks": false,
    "options": { },
    "collaborators": [ ],
    "settings": [ ],
    "owner": {
      // user object
    }
  }
}

Retrieve one Space

Returns a single space object by providing a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space object as response.

Retrieve multiple Spaces

Returns an array of space objects.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of space objects as response.

Create a Space

Property Description
space[name] Name of your space; required
space[domain] Domain for your default preview url
space[story_published_hook] Published Webhook URL
space[searchblok_id] Searchblok id, if available
space[environments] Array of name and location (url) objects
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"space\":{\"name\":\"Example Space\"}}"
// use the universal js client to perform the request
Storyblok.post('spaces/', {
  "space": {
    "name": "Example Space"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "space" =>  {
    "name" =>  "Example Space"
  }
}

client.post('spaces/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"space\":{\"name\":\"Example Space\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"space\":{\"name\":\"Example Space\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"space\":{\"name\":\"Example Space\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"space\":{\"name\":\"Example Space\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"space\":{\"name\":\"Example Space\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space object as response.

Update a Space

You're only able to update the following properties of your space.

Property Description
space[id] Numeric id of your space
space[name] Name of your space
space[domain] Domain for your default preview url
space[uniq_domain] Unique Domain for the Storyblok Rendering Service
space[owner_id] Numeric user id of the owner for that space
space[parent_id] Space id of a possible parent space
space[duplicatable] Is the space globally duplicatable by all users
space[default_root] Default content type used for this space default: page
space[options] Options for backup and language configurations
space[routes] Routes for the Storyblok Rendering Service
space[story_published_hook] Published Webhook URL
space[searchblok_id] Searchblok id, if available
space[environments] Array of name, location (url) objects
space[billing_address] Billing information used to generate your invoices for this space
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/12422/" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"space\":{\"id\":12422,\"name\":\"Updated Example Space\"}}"
// use the universal js client to perform the request
Storyblok.put('spaces/12422/', {
  "space": {
    "id": 12422,
    "name": "Updated Example Space"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "space" =>  {
    "id" =>  12422,
    "name" =>  "Updated Example Space"
  }
}

client.put('spaces/12422/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/12422/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"space\":{\"id\":12422,\"name\":\"Updated Example Space\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/12422/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"space\":{\"id\":12422,\"name\":\"Updated Example Space\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/12422/");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"space\":{\"id\":12422,\"name\":\"Updated Example Space\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"space\":{\"id\":12422,\"name\":\"Updated Example Space\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/12422/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/12422/"

querystring = {}

payload = "{\"space\":{\"id\":12422,\"name\":\"Updated Example Space\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space object as response.

Delete a Space

Delete a space by its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/12422/" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/12422/').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/12422/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/12422/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/12422/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/12422/");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/12422/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/12422/"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Duplicate a Space

Duplicate a space and all it's content entries and components; Assets will not be duplicated and still will reference the original space.

Property Description
space[name] Name of your space; required
space[domain] Domain for your default preview url
space[story_published_hook] Published Webhook URL
space[searchblok_id] Searchblok id, if available
space[environments] Array of name and location (url) objects
space[dup_id] The numeric id of the original space
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"space\":{\"name\":\"Example Space\",\"dup_id\":12422}}"
// use the universal js client to perform the request
Storyblok.post('spaces/', {
  "space": {
    "name": "Example Space",
    "dup_id": 12422
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "space" =>  {
    "name" =>  "Example Space",
    "dup_id" =>  12422
  }
}

client.post('spaces/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"space\":{\"name\":\"Example Space\",\"dup_id\":12422}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"space\":{\"name\":\"Example Space\",\"dup_id\":12422}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"space\":{\"name\":\"Example Space\",\"dup_id\":12422}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"space\":{\"name\":\"Example Space\",\"dup_id\":12422}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"space\":{\"name\":\"Example Space\",\"dup_id\":12422}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space object as response.

Backup a Space

Trigger the backup task for your space. Make sure you've configured backups in your space options.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/12422/backups" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{}"
// use the universal js client to perform the request
Storyblok.post('spaces/12422/backups', {}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {}

client.post('spaces/12422/backups', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/12422/backups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/12422/backups")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/12422/backups");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/12422/backups")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/12422/backups"

querystring = {}

payload = "{}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space object as response.

Space Roles

Space roles are custom permission sets that can be attached to collaborators to define their roles and permissions in a specific space.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/space_roles/:space_role_id

The Space Role Object

Property Description
id Numeric Unique ID
role Name used in the interface
access_tasks Is allowed to access the Tasks menu item
allowed_paths Story ids the user should have access to (acts as whitelist). If no item is selected the user has rights to access all content items.
resolved_allowed_paths Resolved allowed_paths for displaying paths
field_permissions Hide specific fields for this user with an array of strings with the schema: "component_name.field_name"
permissions Allow specific actions in interface by adding the permission as array of strings

Possible Permissions

Permission Description
publish_stories Allow publishing of content entries
save_stories Allow editing and saving of content entries
edit_datasources Allow editing and saving of datasources
access_commerce Allow access to commerce app
edit_story_slug Deny the change of slugs of content entries
move_story Deny moving of content entries
view_composer Deny access to visual composer
Edit this section on GitHub

Example Object

{
  "space_role": {
    "id": 18,
    "role": "English User",
    "access_tasks": true,
    "resolved_allowed_paths": [

    ],
    "allowed_paths": [
      12412,
      51122
    ],
    "field_permissions": [

    ],
    "permissions": [

    ]
  }
}

Retrieve one Space Role

Returns a single, space role object by providing a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/space_roles/18" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/space_roles/18', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/space_roles/18')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/space_roles/18",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/space_roles/18")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/space_roles/18");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/space_roles/18")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/space_roles/18"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space role object as response.

Retrieve multiple Space Role

Returns an array of space role objects.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/space_roles/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/space_roles/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/space_roles/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/space_roles/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/space_roles/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/space_roles/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/space_roles/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will an array of space role objects as response.

Create a Space Role

Property Description
space_role Your space role object
space_role[name] The space role name is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/656/space_roles/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"space_role\":{\"role\":\"English User\"}}"
// use the universal js client to perform the request
Storyblok.post('spaces/656/space_roles/', {
  "space_role": {
    "role": "English User"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "space_role" =>  {
    "role" =>  "English User"
  }
}

client.post('spaces/656/space_roles/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/656/space_roles/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"space_role\":{\"role\":\"English User\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/656/space_roles/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"space_role\":{\"role\":\"English User\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/space_roles/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"space_role\":{\"role\":\"English User\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"space_role\":{\"role\":\"English User\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/656/space_roles/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/656/space_roles/"

querystring = {}

payload = "{\"space_role\":{\"role\":\"English User\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space role object as response.

Update a Space Role

Property Description
space_role Your full component object
space_role[name] The space role name is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/656/space_roles/18" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"space_role\":{\"id\":18,\"role\":\"English Editor\"}}"
// use the universal js client to perform the request
Storyblok.put('spaces/656/space_roles/18', {
  "space_role": {
    "id": 18,
    "role": "English Editor"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "space_role" =>  {
    "id" =>  18,
    "role" =>  "English Editor"
  }
}

client.put('spaces/656/space_roles/18', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/656/space_roles/18",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"space_role\":{\"id\":18,\"role\":\"English Editor\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/656/space_roles/18")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"space_role\":{\"id\":18,\"role\":\"English Editor\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/space_roles/18");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"space_role\":{\"id\":18,\"role\":\"English Editor\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"space_role\":{\"id\":18,\"role\":\"English Editor\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/656/space_roles/18")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/656/space_roles/18"

querystring = {}

payload = "{\"space_role\":{\"id\":18,\"role\":\"English Editor\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a space role object as response.

Delete a Space Role

Delete a space role using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/space_roles/18" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/space_roles/18').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/space_roles/18')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/space_roles/18",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/space_roles/18")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/space_roles/18");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/space_roles/18")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/space_roles/18"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Tasks

You can create a Tasks that editor can press to send requests to one of your custom endpoints to either trigger a build for production or other common use-cases like product syncs or other publishing tasks. Future updates will also bring scheduled and timed tasks so you can handle all your tasks at one place.

The payload Storyblok will send to your webhook url as POST request:

{
  "task": {
    "id": 214, 
    "name": "My Task Name"
  }, 
  "space_id": 606
}
Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/tasks/:task_id

The Task Object

Property Description
id Numeric ID of your task
name Given name of your task
description A brief description of your task for your editors
task_type Default: webhook; Currently available: webhook
last_execution Date and time of last execution (Format: YYYY-mm-dd HH:MM)
webhook_url URL of webhook that should be called when tasks is being executed
last_response Last execution response log
lambda_code Beta: Lambda function code
Edit this section on GitHub

Example Object

{
  "task": {
    "id": 124,
    "name": "My Task Name",
    "description": null,
    "task_type": "webhook",
    "last_execution": null,
    "lambda_code": null,
    "last_response": null,
    "webhook_url": "https://www.storyblok.com"
  }
}

Retrieve one Task

Returns a single task object with a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/tasks/124" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/tasks/124', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/tasks/124')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/tasks/124",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/tasks/124")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/tasks/124");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/tasks/124")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/tasks/124"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a task object as response.

Retrieve multiple Tasks

Returns an array of task objects. This endpoint is paged.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/tasks/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/tasks/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/tasks/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/tasks/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/tasks/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/tasks/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/tasks/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of task objects as response.

Create a Task

Property Description
task Your full task object
task[name] Name is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/tasks/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"task\":{\"name\":\"My Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/tasks/', {
  "task": {
    "name": "My Task Name",
    "task_type": "webhook",
    "webhook_url": "https://www.storyblok.com"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "task" =>  {
    "name" =>  "My Task Name",
    "task_type" =>  "webhook",
    "webhook_url" =>  "https => //www.storyblok.com"
  }
}

client.post('spaces/606/tasks/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/tasks/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"task\":{\"name\":\"My Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/tasks/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"task\":{\"name\":\"My Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/tasks/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"task\":{\"name\":\"My Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"task\":{\"name\":\"My Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/tasks/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"task\":{\"name\":\"My Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded task object as response.

Update a Task

Property Description
task Your full task object
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/tasks/124" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"task\":{\"name\":\"My Updated Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}"
// use the universal js client to perform the request
Storyblok.put('spaces/606/tasks/124', {
  "task": {
    "name": "My Updated Task Name",
    "task_type": "webhook",
    "webhook_url": "https://www.storyblok.com"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "task" =>  {
    "name" =>  "My Updated Task Name",
    "task_type" =>  "webhook",
    "webhook_url" =>  "https => //www.storyblok.com"
  }
}

client.put('spaces/606/tasks/124', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/tasks/124",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"task\":{\"name\":\"My Updated Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/606/tasks/124")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"task\":{\"name\":\"My Updated Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/tasks/124");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"task\":{\"name\":\"My Updated Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"task\":{\"name\":\"My Updated Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/tasks/124")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/tasks/124"

querystring = {}

payload = "{\"task\":{\"name\":\"My Updated Task Name\",\"task_type\":\"webhook\",\"webhook_url\":\"https://www.storyblok.com\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded task object as response.

Delete a Task

Delete a task by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/tasks/124" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/tasks/124').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/tasks/124')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/tasks/124",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/tasks/124")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/tasks/124");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/tasks/124")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/tasks/124"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Approvals

Triggers a approval message for a specific content entry. It allows you to send an approval request to another collaborator of the space.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/approvals/:approval_id

The Approval Object

Property Description
id Numeric Unique ID
status Status of approval
story_id ID of content entry that should be approved
approver_id ID of the User that should be the approver
Edit this section on GitHub

Example Object

{
  "approval": {
    "id": 11,
    "status": "pending",
    "story_id": 1066,
    "approver_id": 1028
  }
}

Retrieve one Approval

Returns a single approval object with a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/approvals/5405" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/approvals/5405', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/approvals/5405')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/approvals/5405",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/approvals/5405")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/approvals/5405");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/approvals/5405")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/approvals/5405"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a approval object as response.

Retrieve multiple Activities

Returns an array of approval objects. This endpoint can be filtered on approver and is paged.

Parameter Description
approver Numeric Id of the approver
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/approvals/?approver=1028" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/approvals/', {
  "approver": 1028
})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/approvals/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/approvals/?approver=1028",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/approvals/?approver=1028")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/approvals/?approver=1028");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/approvals/?approver=1028")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {"approver":1028}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of approval objects as response.

Create Approval

Property Description
story_id ID of content entry that should be approved
approver_id ID of the User that should be the approver
Edit this section on GitHub

Example Request Object

{
  "approval": {
    "story_id": 1066,
    "approver_id": 1028
  }
}

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/approvals/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"approval\":{\"story_id\":1066,\"approver_id\":1028}}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/approvals/', {
  "approval": {
    "story_id": 1066,
    "approver_id": 1028
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "approval" =>  {
    "story_id" =>  1066,
    "approver_id" =>  1028
  }
}

client.post('spaces/606/approvals/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/approvals/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"approval\":{\"story_id\":1066,\"approver_id\":1028}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/approvals/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"approval\":{\"story_id\":1066,\"approver_id\":1028}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/approvals/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"approval\":{\"story_id\":1066,\"approver_id\":1028}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"approval\":{\"story_id\":1066,\"approver_id\":1028}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/approvals/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"approval\":{\"story_id\":1066,\"approver_id\":1028}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Example Response Object

{
  "approval": {
    "id": 11,
    "status": "pending"
  }
}

Create Release Approval

Property Description
story_id ID of content entry that should be approved
approver_id ID of the User that should be the approver
release_id ID of the release that should be approved
Edit this section on GitHub

Example Request Object

{
  "approval": {
    "story_id": 1067,
    "approver_id": 1030
  },
  "release_id": 16
}

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/approvals/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"approval\":{\"story_id\":1066,\"approver_id\":1028},\"release_id\":16}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/approvals/', {
  "approval": {
    "story_id": 1066,
    "approver_id": 1028
  },
  "release_id": 16
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "approval" =>  {
    "story_id" =>  1066,
    "approver_id" =>  1028
  },
  "release_id" =>  16
}

client.post('spaces/606/approvals/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/approvals/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"approval\":{\"story_id\":1066,\"approver_id\":1028},\"release_id\":16}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/approvals/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"approval\":{\"story_id\":1066,\"approver_id\":1028},\"release_id\":16}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/approvals/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"approval\":{\"story_id\":1066,\"approver_id\":1028},\"release_id\":16}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"approval\":{\"story_id\":1066,\"approver_id\":1028},\"release_id\":16}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/approvals/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"approval\":{\"story_id\":1066,\"approver_id\":1028},\"release_id\":16}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Example Response Object

{
  "approval": {
    "id": 12,
    "status": "pending"
  }
}

Delete an Approval

Delete an approval by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/approvals/5405" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/approvals/5405').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/approvals/5405')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/approvals/5405",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/approvals/5405")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/approvals/5405");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/approvals/5405")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/approvals/5405"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Activities

Activities are created on update, create and delete actions in Storyblok for resources like stories, components, spaces, datasources and datasource entries.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/activities/:activity_id

The Activity Object

Property Description
id Numeric Unique ID
trackable_id Id of reference object that was changes
trackable_type Type of the referenced object
owner_id Id of User that created the object
owner_type Default: "User"
key Key defined by type.action (eg: story.create, story.update, component.create)
parameters Additional parameter passed; Default: null
recipient_id Default: null
recipient_type Default: null
created_at Creation date (Format: YYYY-mm-dd HH:MM)
updated_at Latest update date (Format: YYYY-mm-dd HH:MM)
space_id Space ID reference
Edit this section on GitHub

Example Object

{
  "activity": {
    "id": 5405,
    "trackable_id": null,
    "trackable_type": null,
    "owner_id": null,
    "owner_type": null,
    "key": null,
    "parameters": {
    },
    "recipient_id": null,
    "recipient_type": null,
    "created_at": "2018-11-10T15:32:58.649Z",
    "updated_at": "2018-11-10T15:32:58.649Z",
    "space_id": 606
  }
}

Retrieve one Activity

Returns a single activity object with a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/activities/5405" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/activities/5405', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/activities/5405')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/activities/5405",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/activities/5405")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/activities/5405");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/activities/5405")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/activities/5405"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded activity object as response.

Retrieve multiple Activities

Returns an array of activity objects. Can be filtered on date ranges and is paged.

Parameter Description
created_at_gte Activity creation date is greater than YYYY-MM-DD
created_at_lte Activity creation date is lower than YYYY-MM-DD
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/activities/?created_at_gte=2018-12-14&created_at_lte=2018-12-18" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/activities/', {
  "created_at_gte": "2018-12-14",
  "created_at_lte": "2018-12-18"
})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/activities/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/activities/?created_at_gte=2018-12-14&created_at_lte=2018-12-18",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/activities/?created_at_gte=2018-12-14&created_at_lte=2018-12-18")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/activities/?created_at_gte=2018-12-14&created_at_lte=2018-12-18");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/activities/?created_at_gte=2018-12-14&created_at_lte=2018-12-18")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {"created_at_gte":"2018-12-14","created_at_lte":"2018-12-18"}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of activity objects as response.

Presets

As a developer, you can now define multiple default values for your components. For example, a teaser component can have three styles:

  • teaser with a background image
  • teaser with text only and solid background color
  • teaser with a call to action button.

To make it easier for the editor to find the necessary configuration of this three styles you can save it as presets and upload a screenshot.

Edit this section on GitHub

Endpoint

GET /v1/spaces/:space_id/presets/:preset_id

The Preset Object

Property Description
id Numeric ID of your preset
name Given name of your preset
preset[preset] Object with the fields you want to save in the preset
component_id ID of the component the preset should be connected
image Screenshot or other preview image for your editor; Default: null
created_at Creation date (Format: YYYY-mm-dd HH:MM)
updated_at Latest update date (Format: YYYY-mm-dd HH:MM)
Edit this section on GitHub

Example Object

{
  "preset": {
    "id": 1814,
    "name": "Teaser with filled headline",
    "preset": {
      // fields of the component filled with content
      "headline": "This is a default value for the preset!",
      ...
    },
    "component_id": 62,
    "space_id": 606,
    "image": "//a.storyblok.com/f/606/...",
    "created_at": "2018-11-10T15:33:16.726Z",
    "updated_at": "2018-11-10T15:33:16.726Z"
  }
}

Retrieve one Preset

Returns a single preset object with a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/presets/1814" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/presets/1814', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/presets/1814')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/presets/1814",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/presets/1814")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/presets/1814");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/presets/1814")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/presets/1814"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a preset object as response.

Retrieve multiple Presets

Returns an array of preset objects.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/presets/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('spaces/606/presets/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('spaces/606/presets/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/presets/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/606/presets/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/presets/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/presets/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

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

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive an array of preset objects as response.

Create a Preset

Property Description
preset Your full preset object
preset[name] Name is required
preset[component_id] Use numeric component id for referencing
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/presets/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"preset\":{\"name\":\"Teaser with filled headline\",\"preset\":{\"headline\":\"This is a default value for the preset!\"},\"component_id\":62}}"
// use the universal js client to perform the request
Storyblok.post('spaces/606/presets/', {
  "preset": {
    "name": "Teaser with filled headline",
    "preset": {
      "headline": "This is a default value for the preset!"
    },
    "component_id": 62
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "preset" =>  {
    "name" =>  "Teaser with filled headline",
    "preset" =>  {
      "headline" =>  "This is a default value for the preset!"
    },
    "component_id" =>  62
  }
}

client.post('spaces/606/presets/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/presets/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"preset\":{\"name\":\"Teaser with filled headline\",\"preset\":{\"headline\":\"This is a default value for the preset!\"},\"component_id\":62}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/606/presets/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"preset\":{\"name\":\"Teaser with filled headline\",\"preset\":{\"headline\":\"This is a default value for the preset!\"},\"component_id\":62}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/presets/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"preset\":{\"name\":\"Teaser with filled headline\",\"preset\":{\"headline\":\"This is a default value for the preset!\"},\"component_id\":62}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"preset\":{\"name\":\"Teaser with filled headline\",\"preset\":{\"headline\":\"This is a default value for the preset!\"},\"component_id\":62}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/presets/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

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

querystring = {}

payload = "{\"preset\":{\"name\":\"Teaser with filled headline\",\"preset\":{\"headline\":\"This is a default value for the preset!\"},\"component_id\":62}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded preset object as response.

Update a Preset

Property Description
preset Your full preset object
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/presets/1814" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"preset\":{\"id\":1814,\"name\":\"Teaser with headline and image\",\"preset\":{\"headline\":\"This is a default value for the preset!\",\"image\":\"//a.storyblok.com/f/606/...\"},\"component_id\":62}}"
// use the universal js client to perform the request
Storyblok.put('spaces/606/presets/1814', {
  "preset": {
    "id": 1814,
    "name": "Teaser with headline and image",
    "preset": {
      "headline": "This is a default value for the preset!",
      "image": "//a.storyblok.com/f/606/..."
    },
    "component_id": 62
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "preset" =>  {
    "id" =>  1814,
    "name" =>  "Teaser with headline and image",
    "preset" =>  {
      "headline" =>  "This is a default value for the preset!",
      "image" =>  "//a.storyblok.com/f/606/..."
    },
    "component_id" =>  62
  }
}

client.put('spaces/606/presets/1814', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/presets/1814",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"preset\":{\"id\":1814,\"name\":\"Teaser with headline and image\",\"preset\":{\"headline\":\"This is a default value for the preset!\",\"image\":\"//a.storyblok.com/f/606/...\"},\"component_id\":62}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/spaces/606/presets/1814")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"preset\":{\"id\":1814,\"name\":\"Teaser with headline and image\",\"preset\":{\"headline\":\"This is a default value for the preset!\",\"image\":\"//a.storyblok.com/f/606/...\"},\"component_id\":62}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/presets/1814");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"preset\":{\"id\":1814,\"name\":\"Teaser with headline and image\",\"preset\":{\"headline\":\"This is a default value for the preset!\",\"image\":\"//a.storyblok.com/f/606/...\"},\"component_id\":62}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"preset\":{\"id\":1814,\"name\":\"Teaser with headline and image\",\"preset\":{\"headline\":\"This is a default value for the preset!\",\"image\":\"//a.storyblok.com/f/606/...\"},\"component_id\":62}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/presets/1814")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/presets/1814"

querystring = {}

payload = "{\"preset\":{\"id\":1814,\"name\":\"Teaser with headline and image\",\"preset\":{\"headline\":\"This is a default value for the preset!\",\"image\":\"//a.storyblok.com/f/606/...\"},\"component_id\":62}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a fully loaded preset object as response.

Delete a Preset

Delete a preset by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/spaces/606/presets/1814" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('spaces/606/presets/1814').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('spaces/606/presets/1814')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/spaces/606/presets/1814",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/spaces/606/presets/1814")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/spaces/606/presets/1814");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/606/presets/1814")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/spaces/606/presets/1814"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Field types

We built Storyblok with a robust and flexible plugin system to give our customers the power to extend the editor with custom fields like a color picker or a google maps location selector. It’s basically a Vue.js 2.5.2 component extended with a few helpers in the ‘window.Storyblok.plugin’ variable.

This endpoint lets you push and pull the code of your field type via the management api and can be used to automatically deploy a plugin.

Read more about field type development.

Edit this section on GitHub

Endpoint

GET /v1/field_types/:id

The Field Type Object

Property Description
id Numeric ID of your field type
name Given name of your field type. Needs to be unique. A personal prefix is recommended (Example: my-geo-selector).
body The uncompiled javascript code of the field type.
compiled_body Used by the online code editor. Needs to be an empty string if using local plugin development.
space_ids Array of space ids where the field type is assigned to.
Edit this section on GitHub

Example Object

{
  "field_type": {
    "id": 124,
    "name": "my-geo-selector",
    "body": "var Fieldtype = {}",
    "compiled_body": "",
    "space_ids": []
  }
}

Retrieve one Field Type

Returns a single field type object with a specific numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/field_types" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('field_types', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('field_types')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/field_types",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/field_types")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/field_types");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/field_types")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/field_types"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a field type object as response.

Retrieve multiple Field Types

Returns an array of field type objects. This endpoint is paged.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/field_types/" \
-X GET \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json"
// use the universal js client to perform the request
Storyblok.get('field_types/', {})
.then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.get('field_types/')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/field_types/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/field_types/")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/field_types/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/field_types/")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/field_types/"

querystring = {}

payload = ""
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a field type object as response.

Create a Field Type

Property Description
field_type Your field type object
field_type[name] Name is required
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/field_types/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"field_type\":{\"name\":\"my-geo-selector\"}}"
// use the universal js client to perform the request
Storyblok.post('field_types/', {
  "field_type": {
    "name": "my-geo-selector"
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "field_type" =>  {
    "name" =>  "my-geo-selector"
  }
}

client.post('field_types/', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/field_types/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"field_type\":{\"name\":\"my-geo-selector\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/field_types/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"field_type\":{\"name\":\"my-geo-selector\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/field_types/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"field_type\":{\"name\":\"my-geo-selector\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"field_type\":{\"name\":\"my-geo-selector\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/field_types/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/field_types/"

querystring = {}

payload = "{\"field_type\":{\"name\":\"my-geo-selector\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a field type object as response.

Update a Field Type

Property Description
field_type Your full field type object.
field_type[body] The javascript code of the field type.
field_type[compiled_body] Used by the online code editor. Needs to be an empty string if using local plugin development.
field_type[space_ids] Array of space ids where the field type is assigned to.
publish If this parameter is not empty the field type will be published.
Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/field_types/124" \ 
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"field_type\":{\"body\":\"const Fieldtype = {}\",\"compiled_body\":\"\"}}"
// use the universal js client to perform the request
Storyblok.put('field_types/124', {
  "field_type": {
    "body": "const Fieldtype = {}",
    "compiled_body": ""
  }
}).then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
  "field_type" =>  {
    "body" =>  "const Fieldtype = {}",
    "compiled_body" =>  ""
  }
}

client.put('field_types/124', payload)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/field_types/124",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"field_type\":{\"body\":\"const Fieldtype = {}\",\"compiled_body\":\"\"}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.put("https://mapi.storyblok.com/v1/field_types/124")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"field_type\":{\"body\":\"const Fieldtype = {}\",\"compiled_body\":\"\"}}")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/field_types/124");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"field_type\":{\"body\":\"const Fieldtype = {}\",\"compiled_body\":\"\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import Foundation

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

let postData = NSData(data: "{\"field_type\":{\"body\":\"const Fieldtype = {}\",\"compiled_body\":\"\"}}".data(using: String.Encoding.utf8)!)

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/field_types/124")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "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()
import requests

url = "https://mapi.storyblok.com/v1/field_types/124"

querystring = {}

payload = "{\"field_type\":{\"body\":\"const Fieldtype = {}\",\"compiled_body\":\"\"}}"
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

You will receive a field type object as response.

Delete a Field Type

Delete a field type by using its numeric id.

Edit this section on GitHub

Example Request

curl "https://mapi.storyblok.com/v1/field_types/1" \ 
-X DELETE \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d ""
// use the universal js client to perform the request
Storyblok.delete('field_types/1').then(response => {
  console.log(response)
}).catch(error => { 
  console.log(error)
})
require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

client.delete('field_types/1')
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://mapi.storyblok.com/v1/field_types/1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => undefined,
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: YOUR_OAUTH_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.delete("https://mapi.storyblok.com/v1/field_types/1")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .asString();
var client = new RestClient("https://mapi.storyblok.com/v1/field_types/1");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
IRestResponse response = client.Execute(request);
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/field_types/1")! as URL,
                    cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

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()
import requests

url = "https://mapi.storyblok.com/v1/field_types/1"

querystring = {}

payload = undefined
headers = {
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)