Retrieve Multiple Stories

/stories

Query Parameters

• token

  required string

  A preview or public access token configured in a space.

• cv

  number

  Used to access a particular cached version of a published story by providing a Unix timestamp. Further information is found under Cache Invalidation.

• version

  string

  Default: published. Possible values: draft, published

• starts_with

  string

  Filter by full_slug. Used to retrieve all stories in a specific folder. Example: starts_with=blog/posts

• search_term

  string

  Search stories by full-text.

• sort_by

  string

  Sort stories in ascending or descending order by a specific property. Possible properties are all default story properties and any custom fields defined in the schema of the story type.

  Default story properties can be used like this:
  sort_by=created_at:desc
sort_by=slug:asc

  Custom fields can be used like this:
  sort_by=content.meta_description:asc
sort_by=content.event_title:desc

  By default, all custom fields are sorted as strings. To sort custom fields with numeric values, it needs to be specified whether they should be treated as float or integer. Examples: sort_by=content.price:asc:float
sort_by=content.event_number:asc:int

• per_page

  number

  Default: 25. Max: 100. Learn more under Pagination.

• page

  number

  Default: 1. Learn more under Pagination.

• by_slugs

  string

  Retrieve stories by comma-separated full_slug. It is possible to specify wildcards by using *. Examples:
  by_slugs=posts/my-third-post,posts/my-second-post
by_slugs=posts/*

• excluding_slugs

  string

  Exclude stories by specifying comma-separated values of full_slug. It is possible to specify wildcards by using *. Examples:
  excluding_slugs=posts/my-third-post,posts/my-second-post
excluding_slugs=posts*

• published_at_gt

  string

  Retrieve stories published after the specified date (Format: yyyy-MM-dd HH:mm)

• published_at_lt

  string

  Retrieve stories published before the specified date (Format: yyyy-MM-dd HH:mm)

• first_published_at_gt

  string

  Retrieve stories first published after the specified date (Format: yyyy-MM-dd HH:mm)

• first_published_at_lt

  string

  Retrieve stories first published before the specified date (Format: yyyy-MM-dd HH:mm)

• in_workflow_stages

  number

  Retrieve stories that are in a particular workflow stage by providing a comma-separated list of workflow stage IDs. Workflow stage IDs can be retrieved via the Management API. Example:
  in_workflow_stages=325604,325605

• content_type

  string

  Retrieve stories of a specific content type. Example: content_type=page

• level

  number

  Retrieve stories located in the specified folder level. Examples:

  level=1 retrieves stories from the root folder
  level=2 retrieves stories from top-level folders
  level=3 retrieves stories from second-level folders

  Only the immediate child stories are included in the response. Stories defined as root for the folder are excluded.

• resolve_relations

  string

  Used to resolve relations to other stories established via a multi-option or single-option field. Resolved relations are included in the rels property of the response. A maximum of 50 stories can be resolved. If this limit is exceeded, the story UUIDs are included in the rel_uuids property of the response and can be used for further API requests (this is handled automatically when using one of Storyblok's official frontend SDKs). Entries can be resolved two levels deep.

  To resolve the stories selected in one field, provide the technical name of the immediate parent component of the field, followed by a . and the field name. To resolve the stories selected in multiple fields, provide a comma-separated list.

  Example: resolve_relations=page.author,page.categories

  Further information can be found in this tutorial.

• excluding_ids

  string

  Exclude specific stories by providing their IDs as a comma-separated string. Example:
  excluding_ids=335015953,335015954

• by_uuids

  string

  Retrieve specific stories by providing their UUIDs as a comma-separated string. Example:
  by_uuids=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776

• by_uuids_ordered

  string

  Retrieve specific stories by providing their UUIDs as a comma-separated string. The order of the stories in the response matches the order in which the UUIDs are listed. Example:
  by_uuids_ordered=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776

• with_tag

  string

  Filter by specific tag(s). Multiple tags can be provided as a comma-separated string (treated like an OR operator). Examples:
  with_tag=featured
with_tag=featured,editors_choice

• is_startpage

  boolean

  Filter by stories defined as root for the folder. is_startpage=1 returns only root stories; is_startpage=0 excludes root stories from the result.

• resolve_links

  enum

  Used to resolve internal links of link fields used in a story. Resolved links are included in the links property of the response. Possible values are story, url, and link. Entries can be resolved two levels deep using resolve_links_level. Learn more in this developer guide.

  Possible values	Description
  link	Provides access to additional information such as a linked story's path, parent_id, is_folder, published, is_startpage, position, alternates, real_path, and more.
  url	If only the path of a linked story is required, this value provides the minimum amount of information in the response.
  story	Resolves and returns the complete story object of a linked story.

• resolve_links_level

  number

  Default: 1. Possible values: 1, 2
  Used to resolve up to two levels of links. For example, if a story has a link field that references another story, the links in this story will also be resolved if resolve_links_level is set to 2.

• from_release

  string

  Used to access a story version associated with a specific release by providing the release ID

• fallback_lang

  string

  Used to define a custom fallback language to handle untranslated fields. As standard, the default language defined in the Storyblok is used.

• language

  string

  Used to obtain translated versions of one or more stories. Accepts any language code that is configured in the Storyblok space. Used in the context of field-level translation.

• filter_query

  string or object

  Filter by (a) specific field(s) of your story type. Filtering by default story properties is not supported. The filter_query parameter accepts an attribute and an operation key in string format. Separate the values by a comma to filter by multiple values. When using the Javascript SDK, the filter_query param is an object.

  Show Filter Query child properties Hide Filter Query child properties

  • is

    string

    Matches a value type (empty, not_empty, empty_array, not_empty_array, true, false, null, not_null)

  • in

    string

    Matches all with the exact specified value

  • not_in

    string

    Matches all without the exact specified value

  • like

    string

    Matches all with the specified value (wildcard allowed)

  • not_like

    string

    Matches all without the specified value (wildcard allowed)

  • any_in_array

    string

    Matches if any of the specified values is contained in the field value (array)

  • all_in_array

    string

    Matches if all specified values are contained in the field value (array)

  • gt_date

    string

    Greater than date (Format: YYYY-mm-dd HH:MM)

  • lt_date

    string

    Lower than date (Format: (Format: YYYY-mm-dd HH:MM))

  • gt_int

    string

    Greater than integer value

  • lt_int

    string

    Lower than integer value

  • gt_float

    string

    Greater than float value

  • lt_float

    string

    Lower than float value

• excluding_fields

  string

  Exclude specific fields defined in the schema of a story type by providing the field names as a comma-separated string. Example:
  excluding_fields=body,meta_description

• resolve_assets

  number

  Used to resolve asset metadata, including custom metadata. The resolved metadata is included in the assets property of the response.

Response Properties

• stories

  The Story Object[]

  An array of story objects

  Show child properties Hide child properties

  • name

    string

    The complete name provided for the story

  • created_at

    string

    Creation date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • published_at

    string

    Latest publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • id

    number

    The numeric ID

  • uuid

    string

    Generated UUID string

  • content

    object

    An object containing the field data associated with the specific story type's specific content structure. Also includes a component property with the story type's technical name.

  • slug

    string

    The slug specific for the story

  • full_slug

    string

    The full slug of the story, combining the parent folder(s) and the designated story slug

  • sort_by_date

    string

    Date defined in the story's entry configuration (Format: YYYY-mm-dd)

  • position

    number

    Numeric representation of the story's position in the folder

  • tag_list

    string[]

    Array of tag names

  • is_startpage

    boolean

    true if the story is defined as root for the folder

  • parent_id

    number

    ID of the parent folder

  • meta_data

    object

    Object to store non-editable data that is exclusively maintained with the Management API

  • group_id

    string

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

  • first_published_at

    string

    First publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • release_id

    number

    ID of the current release (can be requested with the from_release API parameter)

  • lang

    string

    Language code of the current language (can be requested with the language API parameter)

  • path

    string

    Value of the real path defined in the story's entry configuration (usually, this value is only required for Storyblok's Visual Editor)

  • alternates

    object[]

    An array containing objects that provide basic data of the stories defined as alternates of the current story

    Show child properties Hide child properties

    • id

      number

      The numeric ID

    • name

      string

      The complete name provided for the story

    • slug

      string

      The slug specific for the story

    • published

      boolean

      true if a story has been published at least once (even if it is currently in draft)

    • full_slug

      string

      The full slug of the story, combining the parent folder(s) and the designated story slug

    • is_folder

      boolean

      true if the instance constitutes a folder

  • default_full_slug

    string

    Contains the complete slug of the default language (if the app Translatable Slugs is installed)

  • translated_slugs

    object[]

    Array of translated slug objects (if the app Translatable Slugs is installed)

    Show child properties Hide child properties

    • slug

      string

      The slug specific for the story

    • name

      string

      The complete name provided for the story

    • lang

      string

      Language code of the current language (can be requested with the language API parameter)

    • published

      boolean

      true if a story has been published at least once (even if it is currently in draft)

• cv

  number

  Used to access a particular cached version of a published story by providing a Unix timestamp. Further information is found under Cache Invalidation.

• rels

  The Story Object

  Array of resolved stories (if the resolve_relations parameter is in use)

  Show child properties Hide child properties

  • name

    string

    The complete name provided for the story

  • created_at

    string

    Creation date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • published_at

    string

    Latest publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • id

    number

    The numeric ID

  • uuid

    string

    Generated UUID string

  • content

    object

    An object containing the field data associated with the specific story type's specific content structure. Also includes a component property with the story type's technical name.

  • slug

    string

    The slug specific for the story

  • full_slug

    string

    The full slug of the story, combining the parent folder(s) and the designated story slug

  • sort_by_date

    string

    Date defined in the story's entry configuration (Format: YYYY-mm-dd)

  • position

    number

    Numeric representation of the story's position in the folder

  • tag_list

    string[]

    Array of tag names

  • is_startpage

    boolean

    true if the story is defined as root for the folder

  • parent_id

    number

    ID of the parent folder

  • meta_data

    object

    Object to store non-editable data that is exclusively maintained with the Management API

  • group_id

    string

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

  • first_published_at

    string

    First publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • release_id

    number

    ID of the current release (can be requested with the from_release API parameter)

  • lang

    string

    Language code of the current language (can be requested with the language API parameter)

  • path

    string

    Value of the real path defined in the story's entry configuration (usually, this value is only required for Storyblok's Visual Editor)

  • alternates

    object[]

    An array containing objects that provide basic data of the stories defined as alternates of the current story

    Show child properties Hide child properties

    • id

      number

      The numeric ID

    • name

      string

      The complete name provided for the story

    • slug

      string

      The slug specific for the story

    • published

      boolean

      true if a story has been published at least once (even if it is currently in draft)

    • full_slug

      string

      The full slug of the story, combining the parent folder(s) and the designated story slug

    • is_folder

      boolean

      true if the instance constitutes a folder

  • default_full_slug

    string

    Contains the complete slug of the default language (if the app Translatable Slugs is installed)

  • translated_slugs

    object[]

    Array of translated slug objects (if the app Translatable Slugs is installed)

    Show child properties Hide child properties

    • slug

      string

      The slug specific for the story

    • name

      string

      The complete name provided for the story

    • lang

      string

      Language code of the current language (can be requested with the language API parameter)

    • published

      boolean

      true if a story has been published at least once (even if it is currently in draft)

• links

  The Link Object[] or The Story Object[]

  An array of resolved links (dependent on the value of the resolve_links parameter).

  Show Filter Query child properties Hide Filter Query child properties

  • id

    number

    The numeric ID

  • uuid

    string

    Generated UUID string

  • slug

    string

    The full slug of the story or folder

  • path

    Value of the real path defined in the story's entry configuration

  • real_path

    string

    Either the full slug of the story or folder with a leading /, or, if existent, the value of the real path defined in the story's entry configuration with a leading /

  • name

    The complete name of the story or folder

  • published

    true if a story has been published at least once (even if it is currently in draft)

  • parent_id

    number

    ID of the parent folder

  • is_folder

    boolean

    true if the instance constitutes a folder

  • is_startpage

    boolean

    true if the story is defined as root for the folder

  • position

    number

    Numeric representation of the story's position in the folder

  • published_at

    string

    Latest publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ); only included if include_dates=1 is specified

  • created_at

    string

    Creation date (Format: yyyy-MM-dd'T'HH:mm:ssZ); only included if include_dates=1 is specified

  • updated_at

    string

    Latest update date (Format: yyyy-MM-dd'T'HH:mm:ssZ); only included if include_dates=1 is specified

  • alternates

    object

    An array containing objects that provide basic data of the different language versions of a story using Storyblok's Field Level Translation. Important: not to be confused with actual story alternates.

    Show child properties Hide child properties

    • path

      Translated slug of the story (if the app Translatable Slugs is installed; otherwise, it matches the slug of the parent object)

    • name

      Translated name of the story (if the app Translatable Slugs is installed)

    • lang

      Language code of this story variant

    • published

      true if a story has been published at least once (even if it is currently in draft)

    • translated_slug

      Translated slug of the story (if the app Translatable Slugs is installed; otherwise, it matches the slug of the parent object)

  Show Filter Query child properties Hide Filter Query child properties

  • name

    string

    The complete name provided for the story

  • created_at

    string

    Creation date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • published_at

    string

    Latest publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • id

    number

    The numeric ID

  • uuid

    string

    Generated UUID string

  • content

    object

    An object containing the field data associated with the specific story type's specific content structure. Also includes a component property with the story type's technical name.

  • slug

    string

    The slug specific for the story

  • full_slug

    string

    The full slug of the story, combining the parent folder(s) and the designated story slug

  • sort_by_date

    string

    Date defined in the story's entry configuration (Format: YYYY-mm-dd)

  • position

    number

    Numeric representation of the story's position in the folder

  • tag_list

    string[]

    Array of tag names

  • is_startpage

    boolean

    true if the story is defined as root for the folder

  • parent_id

    number

    ID of the parent folder

  • meta_data

    object

    Object to store non-editable data that is exclusively maintained with the Management API

  • group_id

    string

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

  • first_published_at

    string

    First publishing date (Format: yyyy-MM-dd'T'HH:mm:ssZ)

  • release_id

    number

    ID of the current release (can be requested with the from_release API parameter)

  • lang

    string

    Language code of the current language (can be requested with the language API parameter)

  • path

    string

    Value of the real path defined in the story's entry configuration (usually, this value is only required for Storyblok's Visual Editor)

  • alternates

    object[]

    An array containing objects that provide basic data of the stories defined as alternates of the current story

    Show child properties Hide child properties

    • id

      number

      The numeric ID

    • name

      string

      The complete name provided for the story

    • slug

      string

      The slug specific for the story

    • published

      boolean

      true if a story has been published at least once (even if it is currently in draft)

    • full_slug

      string

      The full slug of the story, combining the parent folder(s) and the designated story slug

    • is_folder

      boolean

      true if the instance constitutes a folder

  • default_full_slug

    string

    Contains the complete slug of the default language (if the app Translatable Slugs is installed)

  • translated_slugs

    object[]

    Array of translated slug objects (if the app Translatable Slugs is installed)

    Show child properties Hide child properties

    • slug

      string

      The slug specific for the story

    • name

      string

      The complete name provided for the story

    • lang

      string

      Language code of the current language (can be requested with the language API parameter)

    • published

      boolean

      true if a story has been published at least once (even if it is currently in draft)

• rel_uuids

  string

  An array of all UUIDS of resolvable stories. Only provided if the resolve_relations parameter is in use and the limit of resolvable relations is exceeded.

• link_uuids

  string

  An array of all UUIDS of linked stories. Only provided if the resolve_links parameter is in use and the limit of resolvable links is exceeded.