Managing Stories

Getting a list of stories

Endpoint

GET /v1/spaces/:space_id/stories

Parameters

Name 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 the 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.

Request

Query Parameters

page=0
contain_component=headline
sort_by=name:asc

cURL

curl "https://api.storyblok.com/v1/spaces/913/stories?page=0&contain_component=headline&sort_by=name%3Aasc" -X GET \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxNzg4LCJ0aW1lc3RhbXAiOjE1MzkzMzM5ODR9.fj2lv-g8cP87HKo4IsJuBZbvR2JGOfSTdlhoBMXsKX8" \

Response

Body

{
  "stories": [
    {
      "name": "Test",
      "parent_id": 0,
      "created_at": "2018-10-05T08:46:24.934Z",
      "deleted_at": null,
      "group_id": "6e277466-69db-40e8-be4c-d88549c96ea5",
      "sort_by_date": null,
      "updated_at": "2018-10-05T08:46:24.934Z",
      "published_at": null,
      "id": 1584,
      "uuid": "bf3eadb8-396a-4c0a-9bff-2d4cc9b4a869",
      "is_folder": false,
      "published": false,
      "slug": "test",
      "path": null,
      "full_slug": "test",
      "position": 0,
      "unpublished_changes": null,
      "is_startpage": false,
      "pinned": false,
      "publish_at": null,
      "expire_at": null
    }
  ]
}

Get a single story

Endpoint

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

Request

cURL

curl "https://api.storyblok.com/v1/spaces/912/stories/1583" -X GET \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxNzg1LCJ0aW1lc3RhbXAiOjE1MzkzMzM5ODR9.ShMIfGQZ0m2yI92rVIf46DY47YReJtUWLJyi2g5TEwU" \

Response

Body

{
  "story": {
    "name": "Home",
    "parent_id": 0,
    "group_id": "8702a0f8-e82b-43c1-87d9-6a9ae0dd22c9",
    "alternates": [

    ],
    "created_at": "2018-10-05T08:46:24.806Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-10-05T08:46:24.844Z",
    "published_at": null,
    "id": 1583,
    "uuid": "2863fe9e-dacf-4893-8846-8076b84b7e6f",
    "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": "1538729184"
    },
    "pinned": false,
    "breadcrumbs": [

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

Creating an story

Stories are not published by default. If you want to create a published Story add the parameter publish=1.

Endpoint

POST /v1/spaces/:space_id/stories

Parameters

Name Description
publish If '1' the story will be published immediately after creating
story[name] required Name of the 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] Whether to disable the visual editor
story[default_root] Default root component. (Required if a folder story)
story[is_folder] Whether 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] Whether 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/916/stories" -d '{"story":{"name":"Story 1","content":{"component":"root","body":[]},"path":"/v1/spaces/916/stories"}}' -X POST \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxNzk3LCJ0aW1lc3RhbXAiOjE1MzkzMzM5ODV9.GFmi34VGXA6Tzk6SeX2FlR42i-TLACjQoGNcWbTLI9Q" \

Response

Body

{
  "story": {
    "name": "Story 1",
    "parent_id": 0,
    "group_id": "b24e7ddb-b65b-4c53-a876-4dbc58c10116",
    "alternates": [

    ],
    "created_at": "2018-10-05T08:46:25.273Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-10-05T08:46:25.273Z",
    "published_at": null,
    "id": 1588,
    "uuid": "3c369d60-d946-4771-8c6a-122198477caf",
    "is_folder": false,
    "content": {
      "component": "root",
      "body": [

      ],
      "_uid": "7e3e3eee-fa83-4725-9985-5be84eb7150b"
    },
    "published": false,
    "slug": "9325b210-50dd-438d-a40b-4816a5e93060",
    "path": "/v1/spaces/916/stories",
    "full_slug": "9325b210-50dd-438d-a40b-4816a5e93060",
    "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": "1538729185"
    },
    "pinned": false,
    "breadcrumbs": [

    ],
    "publish_at": null,
    "expire_at": null,
    "last_author": {
      "id": 1797,
      "userid": "susan@hansen.org"
    }
  }
}

Deleting a story

Endpoint

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

Request

cURL

curl "https://api.storyblok.com/v1/spaces/931/stories/1620" -d '' -X DELETE \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxODQyLCJ0aW1lc3RhbXAiOjE1MzkzMzM5ODd9.H8n7S4TNgnHKfZ1lzjh2c5yjqVZp_nuD3EIs00NCTW0" \

Response

Body

{
  "story": {
    "name": "Home",
    "parent_id": 0,
    "group_id": "ba98cf9d-d331-4c2a-9bc5-6749034f7bbe",
    "alternates": [

    ],
    "created_at": "2018-10-05T08:46:27.401Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-10-05T08:46:27.401Z",
    "published_at": null,
    "id": 1620,
    "uuid": "83d248c2-6d00-4a84-bb13-28c0556768eb",
    "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": "1538729187"
    },
    "pinned": false,
    "breadcrumbs": [

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

Updating a story

Endpoint

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

Parameters

Name Description
force_update If '1' it will overwrite a locked story
publish If '1' the story will be published immediately after creating
story[name] required Name of the 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] Whether to disable the visual editor
story[default_root] Default root component. (Required if a folder story)
story[is_folder] Whether 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] Whether 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/917/stories/1590" -d '{"story":{"name":"Story 1","content":{"component":"root","body":[]},"path":"/v1/spaces/917/stories/1590"}}' -X PUT \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"
	-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxODAwLCJ0aW1lc3RhbXAiOjE1MzkzMzM5ODV9.sjIUuypSpFEATMmWZ3ny-lHZrz4jfKHzx-4lcVIjUeQ" \

Response

Body

{
  "story": {
    "name": "Story 1",
    "parent_id": 0,
    "group_id": "53c20712-4b59-42b3-ba29-fb6f019ed9be",
    "alternates": [

    ],
    "created_at": "2018-10-05T08:46:25.383Z",
    "sort_by_date": null,
    "tag_list": [

    ],
    "updated_at": "2018-10-05T08:46:25.412Z",
    "published_at": null,
    "id": 1590,
    "uuid": "b03faefc-0aa7-4b2d-90c6-6babdda085c5",
    "is_folder": false,
    "content": {
      "component": "root",
      "body": [

      ],
      "_uid": "999ec9dd-4dee-4ee4-99d8-843e0cdeb566"
    },
    "published": false,
    "slug": "home",
    "path": "/v1/spaces/917/stories/1590",
    "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": "1538729185"
    },
    "pinned": false,
    "breadcrumbs": [

    ],
    "publish_at": null,
    "expire_at": null,
    "last_author": {
      "id": 1800,
      "userid": "vidal@waters.biz"
    }
  }
}

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