Upload Asset

Uploading assets in Storyblok is a three 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. Lastly, you need to send another request to finalize the process and let Storyblok retrieve the MIME type and the content length for your asset. 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.

spaces/:space_id/assets/

Path Parameters

:space_id
number

Numeric id of a space

Request Body Properties

id
number

The numeric ID

Select a Language

1. Start by requesting a signed upload URL and parameter

Request Example

Request

curl "https://mapi.storyblok.com/v1/spaces/656/assets/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_OAUTH_TOKEN" \
  -d "{\"filename\": \"your_file.jpg\",\"size\": \"400x500\"}"

Request

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.post('/spaces/656/assets/', {
  "filename": "your_file.jpg",
  "size": "400x500"
})
  .then(response => {
    console.log(response)
  }).catch(error => { 
    console.log(error)
  })

Request

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

$payload = [
  "filename" =>  "your_file.jpg",
  "size" =>  "400x500"
];

$client->post('/spaces/656/assets/', $payload)->getBody();

Request

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

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

client.post('/spaces/656/assets/', payload)

Request

HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/656/assets/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"filename\": \"your_file.jpg\",\"size\": \"400x500\"}")
  .asString();

Request

var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/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);

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/656/assets/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)

request.method = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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

dataTask.resume()

Request

import requests

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

querystring = {}

payload = "{\"filename\": \"your_file.jpg\",\"size\": \"400x500\"}"
headers = {
  'Content-Type': "application/json",
  'Authorization': "YOUR_OAUTH_TOKEN"
}

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

print(response.text)

Request Example (with asset folder)

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\",\"asset_folder_id\": 123}"

Request

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.post('/spaces/606/assets/', {
  "filename": "your_file.jpg",
  "size": "400x500",
  "asset_folder_id": 123
})
  .then(response => {
    console.log(response)
  }).catch(error => { 
    console.log(error)
  })

Request

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

$payload = [
  "filename" =>  "your_file.jpg",
  "size" =>  "400x500",
  "asset_folder_id" =>  123
];

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

Request

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

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

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

Request

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\",\"asset_folder_id\": 123}")
  .asString();

Request

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\",\"asset_folder_id\": 123}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

import Foundation

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

let postData = NSData(data: "{\"filename\": \"your_file.jpg\",\"size\": \"400x500\",\"asset_folder_id\": 123}".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.method = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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

dataTask.resume()

Request

import requests

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

querystring = {}

payload = "{\"filename\": \"your_file.jpg\",\"size\": \"400x500\",\"asset_folder_id\": 123}"
headers = {
  'Content-Type': "application/json",
  '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) and to finalize the process:

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
    
    // 3. finalize the upload
    Storyblok.get('spaces/606/assets/' + signed_response_object.id + '/finish_upload').then(response => {
      console.log('https://a.storyblok.com/' + signed_response_object.fields.key + ' uploaded!')
    }).catch(error => { 
      throw error
    })
    console.log('https://a.storyblok.com/' + signed_response_object.fields.key + ' uploaded!')
  })
}

Prev Retrieve Multiple Assets

Next Signed Response Object