---
title: Migrating from Version 1
description: Version 2 of the Content Delivery API changes how languages, caching, parameter validation, and resolved references work. Learn what to adjust when moving from version 1.
url: https://www.storyblok.com/docs/api/content-delivery/v2/migrating-from-v1
---

# Migrating from Version 1

[Version 2 of the Content Delivery API](/docs/api/content-delivery/v2/) 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/`.

> [!WARNING]
> 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:

```bash
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:

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

> [!TIP]
> To learn more, check the [Internationalization concept](/docs/concepts/internationalization).

## Cache version

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

```json
{
  "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](/docs/concepts/caching).

## Parameter validation

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

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

```json
{ "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.

```json
{
  "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](/docs/concepts/references).

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](/docs/concepts/fields#link).

## Added parameters

Version 2 accepts additional parameters:

-   When [retrieving multiple stories](/docs/api/content-delivery/v2/stories/retrieve-multiple-stories#query-parameters), these include `content_type`, `level`, `by_ids`, and `resolve_assets`.
-   When [retrieving a single story](/docs/api/content-delivery/v2/stories/retrieve-a-single-story#query-parameters), 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](/docs/api/content-delivery/v2)

[Developer Concept: Caching](/docs/concepts/caching)

## Pagination

-   [Previous: Introduction](/docs/api/content-delivery/v2)
-   [Next: Get Signed URL](/docs/api/content-delivery/v2/assets/get-signed-url)