Update a Story

PUT

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

Use this endpoint for migrations, updates (new component structure, and more), or bulk actions.

To publish an unpublished story, set the publish parameter to true.

Note

Sending false for the publish parameter does not unpublish a story that is already published. To unpublish a story, use the Unpublish a Story endpoint.

To define alternate versions of a story, set the group_id to the same group_id of the story (or stories) that should be the alternate(s).

Path parameters

• :space_id required number

  Numeric ID of a space

• :story_id required number

  Numeric ID of a story

Request body properties

• story The Story Object

  A story object

• group_id string

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

• force_update string

  Set to 1 to force an update of a locked story.
  A story is locked when another user edits it. Forcing an update via the API causes a content conflict. force_update has no effect if the story is locked as part of a workflow stage.

• release_id number

  Numeric ID of a release

• publish boolean

  To publish the story, set the parameter to true. To save changes without publishing, set it to false.

• lang string

  Language code to publish the story individually (must be enabled in Settings → Internationalization)

Response properties

• story The Story Object

  A story object

Examples

cURL

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

JS

// storyblok-js-client@>=7, node@>=18
import Storyblok from "storyblok-js-client";

const storyblok = new Storyblok({
  oauthToken: "YOUR_PERSONAL_ACCESS_TOKEN",
});

try {
  const response = await storyblok.put('spaces/288868932106293/stories/2141', {
  "force_update": 1,
  "publish": true,
  "story": {
    "content": {
      "body": [],
      "component": "page"
    },
    "id": 2141,
    "name": "Updated Story Name",
    "slug": "story-name"
  }
})
  console.log({ response })
} catch (error) {
  console.log(error)
}

PHP

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

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

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

Java

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

C#

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

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

Python

import requests

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

querystring = {}

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

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

print(response.text)

Ruby

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

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

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

Swift

let storyblok = URLSession(storyblok: .mapi(accessToken: .oauth("YOUR_OAUTH_TOKEN")))
var request = URLRequest(storyblok: storyblok, path: "spaces/288868932106293/stories/2141")
request.httpMethod = "PUT"
request.httpBody = try JSONSerialization.data(withJSONObject: [
    "force_update": 1,
    "publish": true,
    "story": [
        "content": [
            "body": [ ],
            "component": "page",
        ],
        "id": 2141,
        "name": "Updated Story Name",
        "slug": "story-name",
    ],
])
let (data, _) = try await storyblok.data(for: request)
print(try JSONSerialization.jsonObject(with: data))

Kotlin

val client = HttpClient {
    install(Storyblok(MAPI)) {
        accessToken = OAuth("YOUR_OAUTH_TOKEN")
    }
}

val response = client.put("spaces/288868932106293/stories/2141") {
    setBody(buildJsonObject {
        put("force_update", 1)
        put("publish", true)
        putJsonObject("story") {
            putJsonObject("content") {
                putJsonArray("body") { }
                put("component", "page")
            }
            put("id", 2141)
            put("name", "Updated Story Name")
            put("slug", "story-name")
        }
    })
}

println(response.body<JsonElement>())

Request for updating assets in a specific story.

Tip

To add an asset to a story or change an existing asset’s values using this endpoint, the asset object sent as part of the request body must include a specific set of parameters. Omitting any required parameters disables the Edit asset dialog in the UI.

Example Asset Object

{
"component": "image",
"image_file": {
  "alt": "Image alt text",
  "copyright": null,
  "fieldtype": "asset",
  "filename": "<https://a.storyblok.com/f/656/9c40e5/image_file_name.jpg>",
  "focus": null,
  "id": 123456789,
  "name": "",
  "title": null
}
}