Migrating from Version 1

Version 2 of the Content Delivery API changes several behaviors that a version 1 integration relies on. Review the following sections before you switch the base URL: a request that returns the correct response on /v1/cdn/ may return different data or a 422 error on /v2/cdn/.

Caution

Build new projects on version 2. Version 1 receives no updates or new features.

Language versions

Version 1 selects a language using the slug, prefixing the story path with the language code:

GET https://api.storyblok.com/v1/cdn/stories/fr/home?token=YOUR_ACCESS_TOKEN

That approach is ambiguous when a folder shares a name with a language code. For example, in a space with a folder named fr, the path fr/home matches both the French version of home and the story home inside the fr folder.

Version 2 fixes this with a dedicated language parameter, letting the path identify the story:

GET https://api.storyblok.com/v2/cdn/stories/home?language=fr&token=YOUR_ACCESS_TOKEN

Tip

To learn more, check the Internationalization concept.

Cache version

Version 2 responses include a cv property, a space-specific timestamp that increments whenever content changes:

{
  "story": {},
  "cv": 1541863983
}

Passing cv as a query parameter lets the CDN serve the request instead of reaching the backend. Storyblok redirect requests without cv to the latest version, causing a round trip.

Tip

To learn more, check the Caching concept.

Parameter validation

Version 2 validates the parameters sent to the stories endpoints. An unrecognized parameter returns a 422 error with the incorrect parameter name:

GET https://api.storyblok.com/v2/cdn/stories?start_with=products&token=YOUR_ACCESS_TOKEN

{ "error": "Parameter(s) start_with not allowed." }

The correct parameter is starts_with. Version 1 ignored the misspell and returned unfiltered response. If a migrated request starts erroring, check for a misspelled filter first.

Response format

Version 2 adds three top-level properties alongside story or stories:

• cv: the cache version described above.
• rels: resolved references, serialized rather than nested.
• links: resolved links, serialized rather than nested.

{
  "story": {},
  "cv": 1630693219,
  "rels": [],
  "links": []
}

Resolved references and links

Version 2 serializes resolved content into the top-level rels and links arrays instead, so code that reads a resolved story from inside a field needs to look it up by uuid in rels. Version 1 nested the resolved content inside the field that referenced it.

A single request resolves up to 50 referenced stories. Beyond that, the remaining UUIDs appear in rel_uuids and need resolving in follow-up requests.

Tip

To learn more, check the References concept.

Version 2 also adds link as a resolve_links value, returning routing properties such as translated slugs.

Tip

To learn more, check the Fields concept.

Added parameters

Version 2 accepts additional parameters:

• When retrieving multiple stories, these include content_type, level, by_ids, and resolve_assets.
• When retrieving a single story, they include content_type and resolve_assets.
• When adding resolve_assets=1 to the stories endpoints, the response includes a top-level assets property with each asset’s metadata.

Further resources

Content Delivery API

Developer Concept: Caching