Upload and Replace Assets

Upload

Uploading assets to Storyblok is a three-step process.

1. Get signed response

   Use the assets endpoint to request a signed response object.

2. Upload asset

   Upload the asset to Amazon S3 using the post_url included in the signed response object. The content type of the request has to be multipart/form-data. Everything in the fields object of the signed response object needs to be included in the form. Lastly, add the file to be uploaded to the form.

   Example request

   curl --request POST \
   --url https://s3.amazonaws.com/a.storyblok.com \
   --header 'content-type: multipart/form-data' \
   --form key=f/184738/9fe59e1868/mars.jpg \
   --form policy=eyJleHBpcmF0aW9uIjoiMjAyNS0wOS0wNVQxMzo0MToyNFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJhLnN0b3J5Ymxvay5jb20ifSx7ImFjbCI6InB1YmxpYy1yZWFkIn0seyJDYWNoZS1Db250cm9sIjoicHVibGljLCBtYXgtYWdlPTMxNTM2MDAwIn0seyJDb250ZW50LVR5cGUiOiJpbWFnZS9qcGVnIn0seyJrZXkiOiJmLzE4NDczOC85ZmU1OWUxODY4L21hcnMuanBnIn0seyJFeHBpcmVzIjoiU2F0LCAwNSBTZXAgMjAyNiAxMzozMToyNCBHTVQifSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwxLDUyNDI4Nzk5OTldLHsieC1hbXotY3JlZGVudGlhbCI6IkFLSUFJVTYyN0VOVVFUNFJXMjNBLzIwMjUwOTA1L3VzLWVhc3QtMS9zMy9hd3M0X3JlcXVl \
   --form x-amz-algorithm=AWS4-HMAC-SHA256 \
   --form x-amz-credential=AKIAIU627ENUQT4RW23A/20250905/us-east-1/s3/aws4_request \
   --form x-amz-date=20250905T133124Z \
   --form x-amz-signature=df14c58d762e95225b204ed878cdcff4b024920bfa7be86a871e44b48ead2d30 \
   --form acl=public-read \
   --form 'Expires=Sat, 05 Sep 2026 13:31:24 GMT' \
   --form 'Cache-Control=public, max-age=31536000' \
   --form Content-Type=image/jpeg \
   --form file=PATH_TO_FILE

3. Finish upload

   Finally, finish and validate the upload using the dedicated endpoint. This step is optional and only applies if the first request has been made with validate_upload=1.

Replace

The same steps apply to replacing an asset. In the first step, make sure to include the existing asset’s ID in the request body. The second and third steps remain the same.