Managing Stories

Getting a list of stories

Endpoint

GET /v1/spaces/:space_id/stories

Parameters

Name Description
page Current page of stories

Request

Query Parameters

page=1

cURL

curl "https://api.storyblok.com/v1/spaces/152/stories?page=1" -X GET \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyMzksInRpbWVzdGFtcCI6MTUyODY1MjQwNn0.-kItwIHRt8pehVDUn9bknwybzH871UrV3M1FA9cpgbE" \

Response

Body

{
  "stories": [

  ]
}

Get a single story

Endpoint

GET /v1/spaces/:space_id/stories/:id

Request

cURL

curl "https://api.storyblok.com/v1/spaces/151/stories/170" -X GET \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyMzYsInRpbWVzdGFtcCI6MTUyODY1MjQwNn0.BbmRb1Ripi1kcJG17T-hZeONhvjjO9CuTkzK36pPfhg" \

Response

Body

{
  "story": {
    "name": "Home",
    "parent_id": 0,
    "group_id": "ce8d8cb4-da88-4bec-b0e6-2710ae9511d0",
    "alternates": [

    ],
    "created_at": "2018-06-03T17:40:06.684Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-06-03T17:40:06.711Z",
    "published_at": null,
    "id": 170,
    "uuid": "b3fa7992-14b4-4412-abc9-cca3a071af10",
    "is_folder": false,
    "content": {
      "_uid": "xyz",
      "body": [
        {
          "_uid": "a9e16ab8-887f-4001-9548-313a09daeb2a",
          "text": "test1",
          "component": "headline"
        },
        {
          "_uid": "89a3cd23-8fd1-4ddc-abfe-a6396d012d14",
          "text": "test2",
          "component": "headline"
        }
      ],
      "component": "root"
    },
    "published": false,
    "slug": "home",
    "path": null,
    "full_slug": "home",
    "default_root": null,
    "disble_fe_editor": false,
    "parent": null,
    "is_startpage": false,
    "unpublished_changes": null,
    "meta_data": null,
    "imported_at": null,
    "preview_token": {
      "token": "",
      "timestamp": "1528047606"
    },
    "pinned": false,
    "breadcrumbs": [

    ],
    "publish_at": null,
    "expire_at": null
  }
}

Creating an story

Endpoint

POST /v1/spaces/:space_id/stories

Parameters

Name Description
story[name] required Name of story
story[slug] required Slug to be used to receive the story from the api
story[content] JSON tree of the content
story[disble_fe_editor] Wether to disable the visual editor
story[default_root] Defaul root component. (Required if a folder story)
story[is_folder] Wether the story acts as a folder
story[group_id] Group ID. For example to make linkages between language versions
story[path] Url path the editor is opening the story
story[is_startpage] Wether the story is a startpage for this folder
story[parent_id] Id of the parent folder
story[sort_by_date] Sort by date
story[meta_data] Key value pairs to add meta data that is not setting the story status to unpublished changes. Example: User ratings.
story[pinned] To pin the story in the toolbar

Request

cURL

curl "https://api.storyblok.com/v1/spaces/153/stories" -d '{"story":{"name":"Story 1","content":{"component":"root","body":[]},"path":"/v1/spaces/153/stories"}}' -X POST \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyNDIsInRpbWVzdGFtcCI6MTUyODY1MjQwNn0.iJeND3fTcIaArnPKFncXT8FnCfersDJPQFdcTTnjNKM" \

Response

Body

{
  "story": {
    "name": "Story 1",
    "parent_id": 0,
    "group_id": "9bf4fb0b-23c1-42c2-b446-9065dd437422",
    "alternates": [

    ],
    "created_at": "2018-06-03T17:40:06.857Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-06-03T17:40:06.857Z",
    "published_at": null,
    "id": 171,
    "uuid": "41f5804f-0984-4327-9452-31a3cb4252ca",
    "is_folder": false,
    "content": {
      "component": "root",
      "body": [

      ],
      "_uid": "6e0a07ae-c0e8-4d54-afb0-de06fe0e70bb"
    },
    "published": false,
    "slug": "0b78b9bc-f90f-43fe-a7d0-c71d52743b01",
    "path": "/v1/spaces/153/stories",
    "full_slug": "0b78b9bc-f90f-43fe-a7d0-c71d52743b01",
    "default_root": null,
    "disble_fe_editor": false,
    "parent": null,
    "is_startpage": false,
    "unpublished_changes": null,
    "meta_data": null,
    "imported_at": null,
    "preview_token": {
      "token": "",
      "timestamp": "1528047606"
    },
    "pinned": false,
    "breadcrumbs": [

    ],
    "publish_at": null,
    "expire_at": null
  }
}

Deleting a story

Endpoint

DELETE /v1/spaces/:space_id/stories/:id

Request

cURL

curl "https://api.storyblok.com/v1/spaces/166/stories/186" -d '' -X DELETE \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyODEsInRpbWVzdGFtcCI6MTUyODY1MjQwOH0.xY_mFCmIyoMu-v9Kri05VtTlrvXCFZq5891XMUvAP0g" \

Response

Body

{
  "story": {
    "name": "Home",
    "parent_id": 0,
    "group_id": "63b84551-0e0e-4f30-9ad8-2036d3c64b68",
    "alternates": [

    ],
    "created_at": "2018-06-03T17:40:08.114Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-06-03T17:40:08.114Z",
    "published_at": null,
    "id": 186,
    "uuid": "4c32f863-b1f3-4931-b516-a80b89ad5f0d",
    "is_folder": false,
    "content": {
      "_uid": "xyz",
      "body": [
        {
          "_uid": "a9e16ab8-887f-4001-9548-313a09daeb2a",
          "text": "test1",
          "component": "headline"
        },
        {
          "_uid": "89a3cd23-8fd1-4ddc-abfe-a6396d012d14",
          "text": "test2",
          "component": "headline"
        }
      ],
      "component": "root"
    },
    "published": false,
    "slug": "home",
    "path": null,
    "full_slug": "home",
    "default_root": null,
    "disble_fe_editor": false,
    "parent": null,
    "is_startpage": false,
    "unpublished_changes": null,
    "meta_data": null,
    "imported_at": null,
    "preview_token": {
      "token": "",
      "timestamp": "1528047608"
    },
    "pinned": false,
    "breadcrumbs": [

    ],
    "publish_at": null,
    "expire_at": null
  }
}

Updating a story

Endpoint

PUT /v1/spaces/:space_id/stories/:id

Parameters

Name Description
story[name] required Name of story
story[content] JSON tree of the content

Request

cURL

curl "https://api.storyblok.com/v1/spaces/154/stories/172" -d '{"story":{"name":"Story 1","content":{"component":"root","body":[]}}}' -X PUT \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyNDUsInRpbWVzdGFtcCI6MTUyODY1MjQwNn0.V2SEa1EnzI456yWe5_fqx-DX8u9uKHwD2EWdM8QlHrQ" \

Response

Body

{
  "story": {
    "name": "Story 1",
    "parent_id": 0,
    "group_id": "5fc39e23-293d-4db7-86d9-21117fdfa498",
    "alternates": [

    ],
    "created_at": "2018-06-03T17:40:06.926Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-06-03T17:40:06.943Z",
    "published_at": null,
    "id": 172,
    "uuid": "87f354bb-ab72-4de9-bf69-c83a0f5600e2",
    "is_folder": false,
    "content": {
      "component": "root",
      "body": [

      ],
      "_uid": "e1414fe4-dc89-49b1-bd5c-878bd97343d8"
    },
    "published": false,
    "slug": "home",
    "path": null,
    "full_slug": "home",
    "default_root": null,
    "disble_fe_editor": false,
    "parent": null,
    "is_startpage": false,
    "unpublished_changes": true,
    "meta_data": null,
    "imported_at": null,
    "preview_token": {
      "token": "",
      "timestamp": "1528047606"
    },
    "pinned": false,
    "breadcrumbs": [

    ],
    "publish_at": null,
    "expire_at": null
  }
}

Export a story as JSON

ResourceInformation
Endpointhttps://mapi.storyblok.com/v1/spaces/:space_id/stories/:id/export.json
MethodGET
HeaderAuthorization:YOUR_MANAGEMENT_TOKEN

Export a story as XML

ResourceInformation
Endpointhttps://mapi.storyblok.com/v1/spaces/:space_id/stories/:id/export.xml
MethodGET
HeaderAuthorization:YOUR_MANAGEMENT_TOKEN

Import a story as JSON

ResourceInformation
Endpointhttps://mapi.storyblok.com/v1/spaces/:space_id/stories/:id/import.json
MethodPUT
HeaderAuthorization:YOUR_MANAGEMENT_TOKEN
Body{"data":"{ \"a9e16ab8-887f-4001-9548-313a09daeb2a:headline:text\":\"translated1\", \"89a3cd23-8fd1-4ddc-abfe-a6396d012d14:headline:text\":\"translated2\", \"page\":\"285\"}"}

Import a story as XML

ResourceInformation
Endpointhttps://mapi.storyblok.com/v1/spaces/:space_id/stories/:id/import.xml
MethodPUT
HeaderAuthorization:YOUR_MANAGEMENT_TOKEN
Body{"data":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><page filename=\"home\" url=\"home\" id=\"283\"> <name>Home</name> <tags><tag id=\"a9e16ab8-887f-4001-9548-313a09daeb2a:headline:text\" type=\"STRING\"><text><![CDATA[translated1]]></text></tag><tag id=\"89a3cd23-8fd1-4ddc-abfe-a6396d012d14:headline:text\" type=\"STRING\"><text><![CDATA[translated2]]></text></tag> </tags></page>"}

Documentation