From 7137c5e3892f031e1b6f78601a88f0d56ba86b0a Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 16:44:25 +0100
Subject: [PATCH 01/12] Update docs about storyblok

---
 blog/2026-03-20-storyblok-adapters.mdx        |  12 ++
 docs/php/symfony/storyblok/adapters.mdx       | 129 ++++++++++++++++++
 docs/php/symfony/storyblok/cli.mdx            |  32 ++++-
 .../recommended-directory-structure.mdx       |   1 +
 docs/php/symfony/storyblok/index.mdx          |  61 ++-------
 docs/php/symfony/storyblok/webhook.mdx        |  29 ++--
 6 files changed, 195 insertions(+), 69 deletions(-)
 create mode 100644 blog/2026-03-20-storyblok-adapters.mdx
 create mode 100644 docs/php/symfony/storyblok/adapters.mdx

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
new file mode 100644
index 0000000..ecf55a1
--- /dev/null
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -0,0 +1,12 @@
+---
+title: Storyblok Adapter Setup and Usage
+authors: [jannik]
+tags: [storyblok, symfony]
+---
+
+The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring, sensitive token parameters.
+
+[1]: /docs/php/symfony/storyblok/adapters
+[2]: /docs/php/symfony/storyblok
+[3]: /docs/php/symfony/storyblok/cli
+[4]: /docs/php/symfony/storyblok/webhook
diff --git a/docs/php/symfony/storyblok/adapters.mdx b/docs/php/symfony/storyblok/adapters.mdx
new file mode 100644
index 0000000..c41eff5
--- /dev/null
+++ b/docs/php/symfony/storyblok/adapters.mdx
@@ -0,0 +1,129 @@
+---
+sidebar_position: 5
+---
+
+# Adapters
+
+The Storyblok bundle uses adapters to connect to one or multiple Storyblok spaces.
+Each adapter is meant to connect to a single Storyblok space, configured via `StoryblokConfig`.
+
+
+## Setup
+
+Create one adapter class per Storyblok space:
+
+```php title="src/Storyblok/Adapter/AppStoryblokAdapter.php"
+<?php declare(strict_types=1);
+
+namespace App\Storyblok\Adapter;
+
+use Psr\Container\ContainerInterface;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Torr\Storyblok\Adapter\AbstractStoryblokAdapter;
+use Torr\Storyblok\Config\StoryblokConfig;
+
+final class AppStoryblokAdapter extends AbstractStoryblokAdapter
+{
+	public function __construct (
+		ContainerInterface $locator,
+		#[Autowire(env: "STORYBLOK_APP_SPACE_ID")]
+		string $spaceId,
+		#[\SensitiveParameter]
+		#[Autowire(env: "STORYBLOK_APP_MANAGEMENT_TOKEN")]
+		string $managementToken,
+		#[\SensitiveParameter]
+		#[Autowire(env: "STORYBLOK_APP_CONTENT_TOKEN")]
+		string $contentToken,
+		#[\SensitiveParameter]
+		#[Autowire(env: "default::STORYBLOK_APP_WEBHOOK_SECRET")]
+		?string $webhookSecret,
+	)
+	{
+		parent::__construct(
+			$locator,
+			new StoryblokConfig(
+				spaceId: $spaceId,
+				managementToken: $managementToken,
+				contentToken: $contentToken,
+				webhookSecret: $webhookSecret,
+			),
+		);
+	}
+
+	#[\Override]
+	public static function getKey () : string
+	{
+		return "app";
+	}
+
+	#[\Override]
+	public function getDisplayName () : string
+	{
+		return "App Website";
+	}
+
+	#[\Override]
+	public function getStandaloneComponentKeys () : array
+	{
+		return [
+			PageComponent::getKey(),
+			NewsEntryComponent::getKey(),
+		];
+	}
+}
+```
+
+Also define the env vars for this adapter in your `.env` file:
+
+```dotenv title=".env"
+STORYBLOK_APP_SPACE_ID=
+STORYBLOK_APP_MANAGEMENT_TOKEN=
+STORYBLOK_APP_CONTENT_TOKEN=
+STORYBLOK_APP_WEBHOOK_SECRET=
+```
+
+:::info
+Adapter keys must be unique and must be valid ["snail"][snail] strings.
+:::
+
+
+## Configuration
+
+`StoryblokConfig` supports these options:
+
+- `$spaceId` (required): numeric Storyblok space id as string.
+- `$managementToken` (required): management API token.
+- `$contentToken` (required): content API token.
+- `$localeLevel` (optional, default `0`): 0-based slug level where locales are defined.
+- `$webhookSecret` (optional): secret for webhook signature validation.
+- `$allowUrlWebhookSecret` (optional, default `false`): allow URL-based secret fallback (for free Storyblok plans).
+- `$assetToken` (optional): token for signed asset URLs.
+
+
+## Provided Services
+
+<!-- todo: add the info here -->
+
+
+
+## Usage
+
+If you know, which Storyblok adapter you want to use, you can just inject it directly:
+
+```php
+public function __construct (
+	AppStoryblokAdapter $storyblok,
+) {}
+```
+
+Sometimes you need to fetch the storyblok depending on a dynamic value, so you need to use the `StoryblokAdapterRegistry` for that:
+
+```php
+public function example (StoryblokAdapterRegistry $registry)
+{
+	$registry->getByKey("app");
+	$registry->getByKey("123456");
+}
+```
+
+[snail]: /docs/php/symfony/snail/
diff --git a/docs/php/symfony/storyblok/cli.mdx b/docs/php/symfony/storyblok/cli.mdx
index af3c677..6ab3057 100644
--- a/docs/php/symfony/storyblok/cli.mdx
+++ b/docs/php/symfony/storyblok/cli.mdx
@@ -13,11 +13,26 @@ Call the command via:
 bin/console storyblok:*
 ```
 
-## `storyblok:components:overview`
+## Adapter Scope
 
-Renders an overview of all locally registered components, their names and components + stories.
+All commands accept optional adapter keys.
+If no key is passed, all adapters are used.
 
-It also renders a list of all components configured in Storyblok that don't match a local definition.
+```bash
+bin/console storyblok:debug
+bin/console storyblok:debug main
+bin/console storyblok:debug main marketing
+```
+
+
+## `storyblok:debug`
+
+Renders debug details for your configured adapter(s):
+
+- Adapter key and Storyblok space metadata
+- Components used in each adapter
+- Unknown components in the space
+- Component library and asset proxy stats
 
 :::tip
 If you have manually managed components in Storyblok, you can ignore them in this overview.
@@ -26,10 +41,19 @@ However, renamed components are not automatically removed in Storyblok, so this
 :::
 
 
+## `storyblok:definitions:validate`
+
+Validates local component definitions for the selected adapter(s).
+
+
 ## `storyblok:definitions:sync`
 
-Pushes your local component definitions to Storyblok.
+Pushes local component definitions to Storyblok for the selected adapter(s).
 
 By default, you are asked to confirm to sync the structure.
 
 You can pass `--force` to automatically confirm the command. This can be used to automate your deployment.
+
+:::caution
+`--force` is only allowed in production.
+:::
diff --git a/docs/php/symfony/storyblok/components/recommended-directory-structure.mdx b/docs/php/symfony/storyblok/components/recommended-directory-structure.mdx
index ca97290..df18346 100644
--- a/docs/php/symfony/storyblok/components/recommended-directory-structure.mdx
+++ b/docs/php/symfony/storyblok/components/recommended-directory-structure.mdx
@@ -7,6 +7,7 @@ sidebar_position: 30
 ```text
 src/
   └─ Storyblok/
+     ├─ Adapter/
      ├─ Api/
      ├─ Component/
      │  ├─ Block/
diff --git a/docs/php/symfony/storyblok/index.mdx b/docs/php/symfony/storyblok/index.mdx
index ff8922b..6aeebe4 100644
--- a/docs/php/symfony/storyblok/index.mdx
+++ b/docs/php/symfony/storyblok/index.mdx
@@ -18,31 +18,6 @@ This bundle provides helpers for
 
 ## Installation
 
-You need to define various environment variables:
-
-```dotenv
-# your space id as number
-STORYBLOK_SPACE_ID=
-
-# your management token
-STORYBLOK_MANAGEMENT_TOKEN=
-
-# your content token – with `preview` scope
-STORYBLOK_CONTENT_TOKEN=
-```
-
-Then add the base config in `config/packages/storyblok.yaml`:
-
-```yaml
-storyblok:
-    space_id: "%env(STORYBLOK_SPACE_ID)%"
-    management_token: "%env(STORYBLOK_MANAGEMENT_TOKEN)%"
-    content_token: "%env(STORYBLOK_CONTENT_TOKEN)%"
-```
-
-
-Then install the package:
-
 ```shell
 composer require 21torr/storyblok
 ```
@@ -52,34 +27,7 @@ If you are using Symfony Flex you are all set.
 <details>
 	<summary>Manual configuration</summary>
 
-	You need to define various environment variables:
-
-	```dotenv title=".env"
-	# your space id as number
-	STORYBLOK_SPACE_ID=
-
-	# your management token
-	STORYBLOK_MANAGEMENT_TOKEN=
-
-	# your content token – with `preview` scope
-	STORYBLOK_CONTENT_TOKEN=
-
-	# the secret to validate webhooks
-	STORYBLOK_WEBHOOK_SECRET=
-	```
-
-	Then add the base config:
-
-	```yaml title="config/packages/storyblok.yaml"
-	storyblok:
-		space_id: "%env(int:STORYBLOK_SPACE_ID)%"
-		management_token: "%env(STORYBLOK_MANAGEMENT_TOKEN)%"
-		content_token: "%env(STORYBLOK_CONTENT_TOKEN)%"
-		webhook:
-			secret: "%env(STORYBLOK_WEBHOOK_SECRET)%"
-	```
-
-	and load the routing:
+	Load the routing:
 
 	```yaml title="config/routes/storyblok.yaml"
 	storyblok:
@@ -87,3 +35,10 @@ If you are using Symfony Flex you are all set.
 		resource: '@TorrStoryblokBundle/config/routes.yaml'
 	```
 </details>
+
+## Adapter Setup
+
+The bundle is adapter-based.
+You create one adapter per Storyblok space and configure each adapter with its own `StoryblokConfig`.
+
+Continue with the [adapter guide](./adapters) for setup, usage and configuration details.
diff --git a/docs/php/symfony/storyblok/webhook.mdx b/docs/php/symfony/storyblok/webhook.mdx
index 9fe73ae..3a535cd 100644
--- a/docs/php/symfony/storyblok/webhook.mdx
+++ b/docs/php/symfony/storyblok/webhook.mdx
@@ -4,10 +4,10 @@ The Storyblok bundle automatically integrates in to all webhooks that are sent f
 
 ## Installation
 
-After setting up the bundle routes[^1], you need to configure the webhook URL in Storyblok:
+After setting up the bundle routes[^1] and your Storyblok adapter[^2], configure the webhook URL in Storyblok:
 
 ```txt
-https://.../storyblok/webhook
+https://.../storyblok/webhook/<adapter-key>
 ```
 
 
@@ -19,10 +19,12 @@ You should always use webhook secrets to secure your webhook endpoints. The webh
 
 On paid plans, you can use the native **Webhooks Secret** feature. Configure the webhook secret in Storyblok and in your bundle:
 
-```yaml title="config/packages/storyblok.yaml"
-storyblok:
-	webhook:
-		secret: "%env(STORYBLOK_WEBHOOK_SECRET)%"
+```yaml title="config/services.yaml"
+services:
+	storyblok.config.main:
+		class: Torr\Storyblok\Config\StoryblokConfig
+		arguments:
+			$webhookSecret: "%env(STORYBLOK_MAIN_WEBHOOK_SECRET)%"
 ```
 
 ### For Unpaid Plans
@@ -31,17 +33,19 @@ Free plans (that are typically used during development) don't support proper web
 
 For that enable this feature:
 
-```yaml title="config/packages/storyblok.yaml"
-storyblok:
-	webhook:
-		secret: "my-secret"
-		allow_url_secret: true
+```yaml title="config/services.yaml"
+services:
+	storyblok.config.main:
+		class: Torr\Storyblok\Config\StoryblokConfig
+		arguments:
+			$webhookSecret: "my-secret"
+			$allowUrlWebhookSecret: true
 ```
 
 and append the secret to your webhook endpoint URL in the config:
 
 ```txt
-https://.../storyblok/webhook/my-secret
+https://.../storyblok/webhook/<adapter-key>/my-secret
 ```
 
 :::danger
@@ -127,3 +131,4 @@ Make sure to include useful information in the response, as you can then debug y
 
 
 [^1]: Follow the [installation guide](./#installation). You can see the details about setting up the routing if you open the "manual installation" section.
+[^2]: See [adapter setup](./adapters#setup).

From cb16549c1ec4d78e5d7df71e258ba9694b9b86ef Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 16:47:37 +0100
Subject: [PATCH 02/12] Update webhook docs

---
 blog/2026-03-20-storyblok-adapters.mdx |  2 +-
 docs/php/symfony/storyblok/webhook.mdx | 44 ++++++++++++++++++--------
 2 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index ecf55a1..ba1feaa 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -4,7 +4,7 @@ authors: [jannik]
 tags: [storyblok, symfony]
 ---
 
-The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring, sensitive token parameters.
+The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans.
 
 [1]: /docs/php/symfony/storyblok/adapters
 [2]: /docs/php/symfony/storyblok
diff --git a/docs/php/symfony/storyblok/webhook.mdx b/docs/php/symfony/storyblok/webhook.mdx
index 3a535cd..f313fc9 100644
--- a/docs/php/symfony/storyblok/webhook.mdx
+++ b/docs/php/symfony/storyblok/webhook.mdx
@@ -19,12 +19,32 @@ You should always use webhook secrets to secure your webhook endpoints. The webh
 
 On paid plans, you can use the native **Webhooks Secret** feature. Configure the webhook secret in Storyblok and in your bundle:
 
-```yaml title="config/services.yaml"
-services:
-	storyblok.config.main:
-		class: Torr\Storyblok\Config\StoryblokConfig
-		arguments:
-			$webhookSecret: "%env(STORYBLOK_MAIN_WEBHOOK_SECRET)%"
+```php
+<?php declare(strict_types=1);
+
+namespace App\Storyblok\Adapter;
+
+final class AppStoryblokAdapter extends AbstractStoryblokAdapter
+{
+	public function __construct (
+		ContainerInterface $locator,
+		#[\SensitiveParameter]
+		#[Autowire(env: "STORYBLOK_APP_WEBHOOK_SECRET")]
+		string $webhookSecret,
+		// ...
+	)
+	{
+		parent::__construct(
+			$locator,
+			new StoryblokConfig(
+				webhookSecret: $webhookSecret,
+				// ...
+			),
+		);
+	}
+
+	// ...
+}
 ```
 
 ### For Unpaid Plans
@@ -33,13 +53,11 @@ Free plans (that are typically used during development) don't support proper web
 
 For that enable this feature:
 
-```yaml title="config/services.yaml"
-services:
-	storyblok.config.main:
-		class: Torr\Storyblok\Config\StoryblokConfig
-		arguments:
-			$webhookSecret: "my-secret"
-			$allowUrlWebhookSecret: true
+```php
+new StoryblokConfig(
+	webhookSecret: $webhookSecret,
+	allowUrlWebhookSecret: true,
+)
 ```
 
 and append the secret to your webhook endpoint URL in the config:

From 692b9fbe71bf3a383cf65b6b2c380a6301d73f51 Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 16:53:05 +0100
Subject: [PATCH 03/12] Show services in the adapter

---
 blog/2026-03-20-storyblok-adapters.mdx  |  2 +-
 docs/php/symfony/storyblok/adapters.mdx | 48 +++++++++++++++++++++----
 2 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index ba1feaa..d1119b3 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -4,7 +4,7 @@ authors: [jannik]
 tags: [storyblok, symfony]
 ---
 
-The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans.
+The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans. The adapter docs now include all provided adapter services with purpose and usage examples, with plain-text service headlines and minimal access-only code snippets.
 
 [1]: /docs/php/symfony/storyblok/adapters
 [2]: /docs/php/symfony/storyblok
diff --git a/docs/php/symfony/storyblok/adapters.mdx b/docs/php/symfony/storyblok/adapters.mdx
index c41eff5..b3a7e80 100644
--- a/docs/php/symfony/storyblok/adapters.mdx
+++ b/docs/php/symfony/storyblok/adapters.mdx
@@ -102,27 +102,61 @@ Adapter keys must be unique and must be valid ["snail"][snail] strings.
 
 ## Provided Services
 
-<!-- todo: add the info here -->
+On the adapter, you have access to different services for this specific Storyblok space:
+
+
+### Content API
+
+Fetch and transform Storyblok content data (for example stories, links and space data).
+
+```php
+$appStoryblok->contentApi
+```
+
+### Management API
+
+Manage your Storyblok space via the Management API, for example when syncing component definitions.
+
+```php
+$appStoryblok->managementApi
+```
+
+### ID Slug Mapper
+
+Resolve between Story IDs and slugs using the content API.
+
+```php
+$appStoryblok->idSlugMapper
+```
+
+### Request Validator
+
+Validate incoming webhook requests against your adapter webhook configuration.
+
+```php
+$appStoryblok->requestValidator
+```
 
 
 
 ## Usage
 
-If you know, which Storyblok adapter you want to use, you can just inject it directly:
+If you know which Storyblok adapter you want to use, you can inject it directly:
 
 ```php
-public function __construct (
-	AppStoryblokAdapter $storyblok,
-) {}
+function example (AppStoryblokAdapter $storyblok)
+{
+	$storyblok->...
+}
 ```
 
 Sometimes you need to fetch the storyblok depending on a dynamic value, so you need to use the `StoryblokAdapterRegistry` for that:
 
 ```php
-public function example (StoryblokAdapterRegistry $registry)
+function example (StoryblokAdapterRegistry $registry)
 {
 	$registry->getByKey("app");
-	$registry->getByKey("123456");
+	$registry->getBySpaceId("123456");
 }
 ```
 

From 4a7052fec5387fd522775c70bf62ea2e43fabc6b Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 16:56:51 +0100
Subject: [PATCH 04/12] Document services of adapter

---
 blog/2026-03-20-storyblok-adapters.mdx        |   6 +-
 docs/php/symfony/storyblok/adapters.mdx       |   5 +
 docs/php/symfony/storyblok/content-api.mdx    |  87 +++++++++++
 docs/php/symfony/storyblok/id-slug-mapper.mdx |  28 ++++
 docs/php/symfony/storyblok/management-api.mdx | 140 ++++++++++++++++++
 .../symfony/storyblok/request-validator.mdx   |  28 ++++
 6 files changed, 293 insertions(+), 1 deletion(-)
 create mode 100644 docs/php/symfony/storyblok/content-api.mdx
 create mode 100644 docs/php/symfony/storyblok/id-slug-mapper.mdx
 create mode 100644 docs/php/symfony/storyblok/management-api.mdx
 create mode 100644 docs/php/symfony/storyblok/request-validator.mdx

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index d1119b3..2dad2a3 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -4,9 +4,13 @@ authors: [jannik]
 tags: [storyblok, symfony]
 ---
 
-The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans. The adapter docs now include all provided adapter services with purpose and usage examples, with plain-text service headlines and minimal access-only code snippets.
+The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans. The adapter docs now include all provided adapter services with purpose and usage examples, with plain-text service headlines and minimal access-only code snippets. Dedicated pages were added for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8].
 
 [1]: /docs/php/symfony/storyblok/adapters
 [2]: /docs/php/symfony/storyblok
 [3]: /docs/php/symfony/storyblok/cli
 [4]: /docs/php/symfony/storyblok/webhook
+[5]: /docs/php/symfony/storyblok/content-api
+[6]: /docs/php/symfony/storyblok/management-api
+[7]: /docs/php/symfony/storyblok/id-slug-mapper
+[8]: /docs/php/symfony/storyblok/request-validator
diff --git a/docs/php/symfony/storyblok/adapters.mdx b/docs/php/symfony/storyblok/adapters.mdx
index b3a7e80..45a4169 100644
--- a/docs/php/symfony/storyblok/adapters.mdx
+++ b/docs/php/symfony/storyblok/adapters.mdx
@@ -104,6 +104,11 @@ Adapter keys must be unique and must be valid ["snail"][snail] strings.
 
 On the adapter, you have access to different services for this specific Storyblok space:
 
+- [Content API](./content-api)
+- [Management API](./management-api)
+- [ID Slug Mapper](./id-slug-mapper)
+- [Request Validator](./request-validator)
+
 
 ### Content API
 
diff --git a/docs/php/symfony/storyblok/content-api.mdx b/docs/php/symfony/storyblok/content-api.mdx
new file mode 100644
index 0000000..b21e6ad
--- /dev/null
+++ b/docs/php/symfony/storyblok/content-api.mdx
@@ -0,0 +1,87 @@
+---
+sidebar_position: 11
+---
+
+# Content API
+
+The Content API is available on the adapter as:
+
+```php
+$appStoryblok->contentApi
+```
+
+Use it to fetch and hydrate Storyblok content for the configured adapter space.
+
+## Main Methods
+
+### `fetchSingleStory()`
+
+Fetches a single story by slug, id or uuid.
+
+```php
+$appStoryblok->contentApi->fetchSingleStory("home");
+```
+
+### `fetchStories()`
+
+Fetches stories for a specific story class.
+
+```php
+$appStoryblok->contentApi->fetchStories(PageStory::class, "pages/*");
+```
+
+### `fetchAllStories()`
+
+Fetches all stories (optionally filtered by slug pattern).
+
+```php
+$appStoryblok->contentApi->fetchAllStories("pages/*");
+```
+
+### `getSpaceInfo()`
+
+Returns metadata for the current Storyblok space.
+
+```php
+$appStoryblok->contentApi->getSpaceInfo();
+```
+
+### `fetchDatasourceEntries()`
+
+Fetches datasource entries from the Content API.
+
+```php
+$appStoryblok->contentApi->fetchDatasourceEntries("countries");
+```
+
+### `fetchFoldersInPath()`
+
+Fetches folders below a slug prefix.
+
+```php
+$appStoryblok->contentApi->fetchFoldersInPath("pages");
+```
+
+### `fetchFolderTitleMap()`
+
+Fetches a map of local folder URL to folder title.
+
+```php
+$appStoryblok->contentApi->fetchFolderTitleMap("pages");
+```
+
+### `fetchAllLinks()`
+
+Fetches all Storyblok links.
+
+```php
+$appStoryblok->contentApi->fetchAllLinks();
+```
+
+### `fetchSignedAssetUrl()`
+
+Fetches signed asset data for private assets.
+
+```php
+$appStoryblok->contentApi->fetchSignedAssetUrl("https://a.storyblok.com/f/...");
+```
diff --git a/docs/php/symfony/storyblok/id-slug-mapper.mdx b/docs/php/symfony/storyblok/id-slug-mapper.mdx
new file mode 100644
index 0000000..be52168
--- /dev/null
+++ b/docs/php/symfony/storyblok/id-slug-mapper.mdx
@@ -0,0 +1,28 @@
+---
+sidebar_position: 13
+---
+
+# ID Slug Mapper
+
+The ID Slug Mapper is available on the adapter as:
+
+```php
+$appStoryblok->idSlugMapper
+```
+
+Use it to resolve a full slug from a Storyblok id or uuid.
+
+## Main Method
+
+### `getFullSlugById()`
+
+Returns the full slug for the given story id or uuid.
+If the id is unknown, it returns `null`.
+
+```php
+$appStoryblok->idSlugMapper->getFullSlugById("123456789");
+```
+
+```php
+$appStoryblok->idSlugMapper->getFullSlugById("95c8d1da-0f48-41f9-a376-c7bb8f72f23f");
+```
diff --git a/docs/php/symfony/storyblok/management-api.mdx b/docs/php/symfony/storyblok/management-api.mdx
new file mode 100644
index 0000000..fecad43
--- /dev/null
+++ b/docs/php/symfony/storyblok/management-api.mdx
@@ -0,0 +1,140 @@
+---
+sidebar_position: 12
+---
+
+# Management API
+
+The Management API is available on the adapter as:
+
+```php
+$appStoryblok->managementApi
+```
+
+Use it for write operations and administration tasks in the configured Storyblok space.
+
+## Main Methods
+
+### `syncComponent()`
+
+Creates or updates a component definition.
+
+```php
+$appStoryblok->managementApi->syncComponent($componentConfig);
+```
+
+### `getOrCreatedComponentGroupUuid()`
+
+Resolves or creates a component group uuid.
+
+```php
+$appStoryblok->managementApi->getOrCreatedComponentGroupUuid("Content");
+```
+
+### `fetchAllRegisteredComponents()`
+
+Returns all component keys currently registered in the space.
+
+```php
+$appStoryblok->managementApi->fetchAllRegisteredComponents();
+```
+
+### `fetchComponentDefinitions()`
+
+Fetches all component definitions.
+
+```php
+$appStoryblok->managementApi->fetchComponentDefinitions();
+```
+
+### `syncDatasourceEntries()`
+
+Syncs datasource entries from your local mapping.
+
+```php
+$appStoryblok->managementApi->syncDatasourceEntries("countries", $values);
+```
+
+### `fetchDatasourceEntries()`
+
+Fetches datasource entries via the Management API.
+
+```php
+$appStoryblok->managementApi->fetchDatasourceEntries("countries");
+```
+
+### `fetchAllAssets()`
+
+Fetches metadata of all assets.
+
+```php
+$appStoryblok->managementApi->fetchAllAssets();
+```
+
+### `updateAsset()`
+
+Updates an asset by id.
+
+```php
+$appStoryblok->managementApi->updateAsset($assetId, $payload);
+```
+
+### `fetchAssetFolders()`
+
+Fetches the full asset folder tree.
+
+```php
+$appStoryblok->managementApi->fetchAssetFolders();
+```
+
+### `fetchAssetData()`
+
+Fetches metadata for a specific asset id.
+
+```php
+$appStoryblok->managementApi->fetchAssetData($assetId);
+```
+
+### `exportTranslationsXmlFile()`
+
+Exports the translation XML for a story.
+
+```php
+$appStoryblok->managementApi->exportTranslationsXmlFile($storyId);
+```
+
+### `importTranslationsXmlFile()`
+
+Imports translation XML for a story.
+
+```php
+$appStoryblok->managementApi->importTranslationsXmlFile($storyId, $xmlContent);
+```
+
+### `fetchStory()`
+
+Fetches a raw management API story payload by story id.
+
+```php
+$appStoryblok->managementApi->fetchStory($storyId);
+```
+
+### `updateStory()`
+
+Updates a story by story id.
+
+```php
+$appStoryblok->managementApi->updateStory($storyId, $storyJson);
+```
+
+### `sendRequest()`
+
+Low-level method to send arbitrary requests to the Storyblok Management API.
+
+```php
+$appStoryblok->managementApi->sendRequest("components");
+```
+
+## Deprecated
+
+`fetchFolderTitleMap()` and `fetchFoldersInPath()` are deprecated in `ManagementApi`.  
+Use the Content API equivalents instead.
diff --git a/docs/php/symfony/storyblok/request-validator.mdx b/docs/php/symfony/storyblok/request-validator.mdx
new file mode 100644
index 0000000..e00a04f
--- /dev/null
+++ b/docs/php/symfony/storyblok/request-validator.mdx
@@ -0,0 +1,28 @@
+---
+sidebar_position: 14
+---
+
+# Request Validator
+
+The request validator is available on the adapter as:
+
+```php
+$appStoryblok->requestValidator
+```
+
+Use it to validate incoming Storyblok webhook requests for the configured adapter.
+
+## Main Method
+
+### `isValidRequest()`
+
+Validates the request based on your adapter webhook config:
+
+- webhook signature (`webhook-signature`) for paid plans
+- optional URL secret fallback for unpaid plans (`allowUrlWebhookSecret`)
+
+```php
+$appStoryblok->requestValidator->isValidRequest($request, $urlSecret);
+```
+
+If both signature and URL secret are present at the same time, validation fails.

From 6a807c283a4e7054fb97e5e820c892ad133fdfb7 Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 16:58:53 +0100
Subject: [PATCH 05/12] Improve links

---
 blog/2026-03-20-storyblok-adapters.mdx  |  2 +-
 docs/php/symfony/storyblok/adapters.mdx | 13 ++++++++-----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index 2dad2a3..af6c496 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -4,7 +4,7 @@ authors: [jannik]
 tags: [storyblok, symfony]
 ---
 
-The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans. The adapter docs now include all provided adapter services with purpose and usage examples, with plain-text service headlines and minimal access-only code snippets. Dedicated pages were added for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8].
+The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans. The adapter docs now include all provided adapter services with purpose and usage examples, with plain-text service headlines and minimal access-only code snippets. Dedicated pages were added for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8], and linked directly below each service headline in the adapter docs.
 
 [1]: /docs/php/symfony/storyblok/adapters
 [2]: /docs/php/symfony/storyblok
diff --git a/docs/php/symfony/storyblok/adapters.mdx b/docs/php/symfony/storyblok/adapters.mdx
index 45a4169..c669f5e 100644
--- a/docs/php/symfony/storyblok/adapters.mdx
+++ b/docs/php/symfony/storyblok/adapters.mdx
@@ -104,14 +104,11 @@ Adapter keys must be unique and must be valid ["snail"][snail] strings.
 
 On the adapter, you have access to different services for this specific Storyblok space:
 
-- [Content API](./content-api)
-- [Management API](./management-api)
-- [ID Slug Mapper](./id-slug-mapper)
-- [Request Validator](./request-validator)
-
 
 ### Content API
 
+[Content API docs](./content-api)
+
 Fetch and transform Storyblok content data (for example stories, links and space data).
 
 ```php
@@ -120,6 +117,8 @@ $appStoryblok->contentApi
 
 ### Management API
 
+[Management API docs](./management-api)
+
 Manage your Storyblok space via the Management API, for example when syncing component definitions.
 
 ```php
@@ -128,6 +127,8 @@ $appStoryblok->managementApi
 
 ### ID Slug Mapper
 
+[ID Slug Mapper docs](./id-slug-mapper)
+
 Resolve between Story IDs and slugs using the content API.
 
 ```php
@@ -136,6 +137,8 @@ $appStoryblok->idSlugMapper
 
 ### Request Validator
 
+[Request Validator docs](./request-validator)
+
 Validate incoming webhook requests against your adapter webhook configuration.
 
 ```php

From 7dc558a57988d6cc7f758f76024af9c756cce5a6 Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 17:01:10 +0100
Subject: [PATCH 06/12] Update changelog

---
 blog/2026-03-20-storyblok-adapters.mdx | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index af6c496..6853f73 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -4,7 +4,19 @@ authors: [jannik]
 tags: [storyblok, symfony]
 ---
 
-The Storyblok docs were updated for the adapter system, including [adapter setup and configuration][1], updated [installation docs][2], and adapter-aware [CLI][3] and [webhook][4] docs. The adapter setup example now uses `AppStoryblokAdapter` with constructor-based env autowiring and sensitive token parameters. The webhook docs now use simplified `AppStoryblokAdapter` examples for paid and unpaid plans. The adapter docs now include all provided adapter services with purpose and usage examples, with plain-text service headlines and minimal access-only code snippets. Dedicated pages were added for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8], and linked directly below each service headline in the adapter docs.
+The Storyblok docs now include a complete guide for the adapter-based setup.
+
+## New Documentation
+
+- [Adapters guide][1] with setup, configuration and usage.
+- Dedicated docs for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8].
+
+## Updated Existing Pages
+
+- [Storyblok installation page][2] now reflects the adapter-based flow.
+- [CLI docs][3] now describe adapter-scoped commands.
+- [Webhook docs][4] now use `AppStoryblokAdapter` examples
+
 
 [1]: /docs/php/symfony/storyblok/adapters
 [2]: /docs/php/symfony/storyblok

From 7052c25e05f7494f5d452cb35791c6c1b241015f Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 17:08:57 +0100
Subject: [PATCH 07/12] Add remaining docs

---
 blog/2026-03-20-storyblok-adapters.mdx        |  8 +++--
 .../storyblok/backend-edit-url-helper.mdx     | 27 +++++++++++++++
 docs/php/symfony/storyblok/cli.mdx            |  3 ++
 .../storyblok/definitions-synced-event.mdx    | 33 +++++++++++++++++++
 docs/php/symfony/storyblok/index.mdx          |  4 +++
 5 files changed, 73 insertions(+), 2 deletions(-)
 create mode 100644 docs/php/symfony/storyblok/backend-edit-url-helper.mdx
 create mode 100644 docs/php/symfony/storyblok/definitions-synced-event.mdx

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index 6853f73..f889da8 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -10,12 +10,13 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 
 - [Adapters guide][1] with setup, configuration and usage.
 - Dedicated docs for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8].
+- New docs for [Backend Edit URL Helper][9], [Definitions Synced Event][10], and [Webhook Actions][11].
 
 ## Updated Existing Pages
 
 - [Storyblok installation page][2] now reflects the adapter-based flow.
-- [CLI docs][3] now describe adapter-scoped commands.
-- [Webhook docs][4] now use `AppStoryblokAdapter` examples
+- [CLI docs][3] now describe adapter-scoped commands and include the post-sync `StoryblokDefinitionsSyncedEvent` hook.
+- [Webhook docs][4] now use `AppStoryblokAdapter` examples and link to the webhook action mapping details.
 
 
 [1]: /docs/php/symfony/storyblok/adapters
@@ -26,3 +27,6 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 [6]: /docs/php/symfony/storyblok/management-api
 [7]: /docs/php/symfony/storyblok/id-slug-mapper
 [8]: /docs/php/symfony/storyblok/request-validator
+[9]: /docs/php/symfony/storyblok/backend-edit-url-helper
+[10]: /docs/php/symfony/storyblok/definitions-synced-event
+[11]: /docs/php/symfony/storyblok/webhook-actions
diff --git a/docs/php/symfony/storyblok/backend-edit-url-helper.mdx b/docs/php/symfony/storyblok/backend-edit-url-helper.mdx
new file mode 100644
index 0000000..7d42319
--- /dev/null
+++ b/docs/php/symfony/storyblok/backend-edit-url-helper.mdx
@@ -0,0 +1,27 @@
+---
+sidebar_position: 15
+---
+
+# Backend Edit URL Helper
+
+`StoryblokBackendUrlGenerator` generates Storyblok backend edit links.
+
+## Usage
+
+Inject the helper:
+
+```php
+StoryblokBackendUrlGenerator $backendUrlGenerator
+```
+
+Generate edit URL by story object:
+
+```php
+$backendUrlGenerator->generateStoryEditUrl($story);
+```
+
+Generate edit URL by story id and space id:
+
+```php
+$backendUrlGenerator->generateStoryEditUrlById(123456, "98765");
+```
diff --git a/docs/php/symfony/storyblok/cli.mdx b/docs/php/symfony/storyblok/cli.mdx
index 6ab3057..4825203 100644
--- a/docs/php/symfony/storyblok/cli.mdx
+++ b/docs/php/symfony/storyblok/cli.mdx
@@ -57,3 +57,6 @@ You can pass `--force` to automatically confirm the command. This can be used to
 :::caution
 `--force` is only allowed in production.
 :::
+
+On successful sync, the bundle dispatches `StoryblokDefinitionsSyncedEvent`.
+See [Definitions Synced Event](./definitions-synced-event) for listener setup.
diff --git a/docs/php/symfony/storyblok/definitions-synced-event.mdx b/docs/php/symfony/storyblok/definitions-synced-event.mdx
new file mode 100644
index 0000000..8d67eaf
--- /dev/null
+++ b/docs/php/symfony/storyblok/definitions-synced-event.mdx
@@ -0,0 +1,33 @@
+---
+sidebar_position: 16
+---
+
+# Definitions Synced Event
+
+After a successful `storyblok:definitions:sync`, the bundle dispatches `StoryblokDefinitionsSyncedEvent`.
+
+## Event Data
+
+The event provides:
+
+- `io`: `TorrStyle` instance used by the sync command.
+- `adapter`: the adapter that was synced.
+
+## Listener Example
+
+```php
+use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
+use Torr\Storyblok\Event\StoryblokDefinitionsSyncedEvent;
+
+#[AsEventListener]
+public function onDefinitionsSynced (StoryblokDefinitionsSyncedEvent $event) : void
+{
+	$event->io->writeln("Run post-sync work...");
+	$event->adapter->managementApi;
+}
+```
+
+## Notes
+
+- If multiple adapters are synced in one command run, one event is dispatched per adapter.
+- The event is only dispatched on successful sync.
diff --git a/docs/php/symfony/storyblok/index.mdx b/docs/php/symfony/storyblok/index.mdx
index 6aeebe4..09dbef0 100644
--- a/docs/php/symfony/storyblok/index.mdx
+++ b/docs/php/symfony/storyblok/index.mdx
@@ -42,3 +42,7 @@ The bundle is adapter-based.
 You create one adapter per Storyblok space and configure each adapter with its own `StoryblokConfig`.
 
 Continue with the [adapter guide](./adapters) for setup, usage and configuration details.
+
+## Additional Helpers
+
+- [Backend Edit URL Helper](./backend-edit-url-helper)

From 190bb1122fd313cf94a649cee8ad4bb4e25483e8 Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 17:20:38 +0100
Subject: [PATCH 08/12] Add asset proxy docs

---
 blog/2026-03-20-storyblok-adapters.mdx        |  3 +
 .../symfony/storyblok/asset-proxy/index.mdx   | 21 +++++++
 .../asset-proxy/setup-and-configuration.mdx   | 55 +++++++++++++++++++
 .../symfony/storyblok/asset-proxy/usage.mdx   | 42 ++++++++++++++
 docs/php/symfony/storyblok/index.mdx          |  1 +
 5 files changed, 122 insertions(+)
 create mode 100644 docs/php/symfony/storyblok/asset-proxy/index.mdx
 create mode 100644 docs/php/symfony/storyblok/asset-proxy/setup-and-configuration.mdx
 create mode 100644 docs/php/symfony/storyblok/asset-proxy/usage.mdx

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index f889da8..0381b8a 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -11,12 +11,14 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 - [Adapters guide][1] with setup, configuration and usage.
 - Dedicated docs for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8].
 - New docs for [Backend Edit URL Helper][9], [Definitions Synced Event][10], and [Webhook Actions][11].
+- New [Asset Proxy][12] section with setup/configuration and usage details.
 
 ## Updated Existing Pages
 
 - [Storyblok installation page][2] now reflects the adapter-based flow.
 - [CLI docs][3] now describe adapter-scoped commands and include the post-sync `StoryblokDefinitionsSyncedEvent` hook.
 - [Webhook docs][4] now use `AppStoryblokAdapter` examples and link to the webhook action mapping details.
+- [Storyblok index][2] now links to the new Asset Proxy section.
 
 
 [1]: /docs/php/symfony/storyblok/adapters
@@ -30,3 +32,4 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 [9]: /docs/php/symfony/storyblok/backend-edit-url-helper
 [10]: /docs/php/symfony/storyblok/definitions-synced-event
 [11]: /docs/php/symfony/storyblok/webhook-actions
+[12]: /docs/php/symfony/storyblok/asset-proxy
diff --git a/docs/php/symfony/storyblok/asset-proxy/index.mdx b/docs/php/symfony/storyblok/asset-proxy/index.mdx
new file mode 100644
index 0000000..a513437
--- /dev/null
+++ b/docs/php/symfony/storyblok/asset-proxy/index.mdx
@@ -0,0 +1,21 @@
+---
+sidebar_position: 18
+---
+
+# Asset Proxy
+
+The Storyblok Asset Proxy lets your application serve Storyblok assets through your own app URL.
+
+Instead of directly serving `https://a.storyblok.com/...`, the URL is rewritten to your app, signed, and cached on disk.
+
+## What This Means for Your Application
+
+- Asset URLs are served from your application domain.
+- Asset files are cached locally in `var/storyblok/assets` by default.
+- Replaced and deleted assets are automatically invalidated when asset webhooks are enabled.
+- Proxy URLs are signed, so only valid generated URLs are accepted.
+
+## Pages
+
+- [Setup and Configuration](./setup-and-configuration)
+- [Usage](./usage)
diff --git a/docs/php/symfony/storyblok/asset-proxy/setup-and-configuration.mdx b/docs/php/symfony/storyblok/asset-proxy/setup-and-configuration.mdx
new file mode 100644
index 0000000..9cb4c49
--- /dev/null
+++ b/docs/php/symfony/storyblok/asset-proxy/setup-and-configuration.mdx
@@ -0,0 +1,55 @@
+---
+sidebar_position: 10
+---
+
+# Setup and Configuration
+
+## Routing
+
+Load the bundle routes so the asset proxy endpoint is available:
+
+```yaml title="config/routes/storyblok.yaml"
+storyblok:
+	prefix: /storyblok/
+	resource: "@TorrStoryblokBundle/config/routes.yaml"
+```
+
+The proxy route is:
+
+```txt
+/storyblok/asset/{spaceId}/{path}
+```
+
+## Storage Path
+
+By default, proxied files are stored in:
+
+```txt
+%kernel.project_dir%/var/storyblok/assets
+```
+
+You can override this path via service configuration:
+
+```yaml title="config/services.yaml"
+services:
+	Torr\Storyblok\Assets\Proxy\AssetProxy:
+		arguments:
+			$storagePath: "%kernel.project_dir%/var/custom-storyblok-assets"
+```
+
+## Webhook Integration for Cache Invalidation
+
+Asset proxy cache invalidation is triggered by asset webhooks:
+
+- `AssetReplaced`
+- `AssetDeleted`
+
+So make sure your Storyblok webhook is configured and asset events are enabled.
+
+## Clearing the Proxy Cache
+
+Clear all cached proxy files:
+
+```bash
+bin/console storyblok:assets:clear-proxy-storage
+```
diff --git a/docs/php/symfony/storyblok/asset-proxy/usage.mdx b/docs/php/symfony/storyblok/asset-proxy/usage.mdx
new file mode 100644
index 0000000..30165d5
--- /dev/null
+++ b/docs/php/symfony/storyblok/asset-proxy/usage.mdx
@@ -0,0 +1,42 @@
+---
+sidebar_position: 20
+---
+
+# Usage
+
+## Rewriting Asset URLs
+
+Use `AssetProxyUrlGenerator` to rewrite Storyblok asset URLs to signed proxy URLs:
+
+```php
+$assetProxyUrlGenerator->rewriteAssetUrl($storyblokAssetUrl);
+```
+
+If the URL is not a Storyblok asset URL, it is returned unchanged.
+
+## Request Flow
+
+1. Your app generates a signed proxy URL.
+2. The request hits `/storyblok/asset/{spaceId}/{path}`.
+3. The signature is validated.
+4. If the file is not cached, it is downloaded from Storyblok and stored locally.
+5. The cached file is streamed to the response.
+
+If the URL signature is invalid, the proxy returns `404`.
+
+## Download Behavior
+
+You can force file download by adding `download` as query parameter:
+
+```txt
+?download=1
+```
+
+Without it, files are returned as inline responses.
+
+## Application Impact
+
+- First request for an asset path is slower (cache miss + download).
+- Following requests are faster (local file hit).
+- Disk usage grows with cached assets.
+- Webhook invalidation keeps replaced/deleted assets fresh.
diff --git a/docs/php/symfony/storyblok/index.mdx b/docs/php/symfony/storyblok/index.mdx
index 09dbef0..c2cdba8 100644
--- a/docs/php/symfony/storyblok/index.mdx
+++ b/docs/php/symfony/storyblok/index.mdx
@@ -46,3 +46,4 @@ Continue with the [adapter guide](./adapters) for setup, usage and configuration
 ## Additional Helpers
 
 - [Backend Edit URL Helper](./backend-edit-url-helper)
+- [Asset Proxy](./asset-proxy)

From bfe86d1c65ecba65737a6e46c837b9d519cacd0d Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 17:20:49 +0100
Subject: [PATCH 09/12] Add API docs

---
 docs/php/symfony/storyblok/api/index.mdx | 89 ++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 docs/php/symfony/storyblok/api/index.mdx

diff --git a/docs/php/symfony/storyblok/api/index.mdx b/docs/php/symfony/storyblok/api/index.mdx
new file mode 100644
index 0000000..63a16ec
--- /dev/null
+++ b/docs/php/symfony/storyblok/api/index.mdx
@@ -0,0 +1,89 @@
+# API
+
+Besides the [content api] and [management api], it is recommended to add a storyblok API, which is a wrapper for the content api and helps with purpose-built fetch methods.
+
+This way all your knowledge about the structure and types of your Storyblok space are encapsulated in one place.
+
+
+```php
+use Symfony\Component\DependencyInjection\Attribute\Exclude;
+
+#[Exclude]
+class AppStoryblokApi
+{
+	public function __construct (
+		private readonly ContentApi $contentApi,
+	) {}
+
+	/**
+	 * @return NewsStory[]
+	 */
+	public function fetchNews (string $pageTree, string $locale)
+	{
+		return $this->contentApi->fetchStories(
+			storyType: NewsStory::class,
+			slug: \sprintf("%s/%s/news/*", $pageTree, $locale),
+			version: $version,
+		);
+	}
+}
+```
+
+Wire it up in your adapter:
+
+```php
+class AppStoryblokAdapter
+{
+	public readonly AppStoryblokApi $api;
+
+	public function __construct (...)
+	{
+		$this->api = new AppStoryblokApi($this->contentApi);
+	}
+```
+
+And use it like this:
+
+```php
+$appStoryblok->api->fetchNews("website", "de-de")
+```
+
+## Caching
+
+If your API client is caching, you need to reset the cache regularly. As the API is not a service itself but just wrapped inside the adapter, you need to forward the call.
+
+First mark your adapter as resettable:
+
+```php
+use Symfony\Contracts\Service\ResetInterface;
+
+class AppStoryblokAdapter extends AbstractStoryblokAdapter implements ResetInterface
+{
+	public readonly AppStoryblokApi $api;
+
+	public function reset ()
+	{
+		$this->api->reset();
+	}
+}
+```
+
+Then implement the cache reset in your API client:
+
+```php
+use Symfony\Contracts\Service\ResetInterface;
+
+class AppStoryblokApi implements ResetInterface
+{
+	public function reset ()
+	{
+		$this->cache = [];
+	}
+}
+```
+
+
+
+
+[content api]: ./content-api
+[management api]: ./management-api

From 611223a2b5c0697cb4b583669e5a0d167f3744c8 Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 17:22:12 +0100
Subject: [PATCH 10/12] Move API to the correct folder

---
 blog/2026-03-20-storyblok-adapters.mdx                  | 4 ++--
 docs/php/symfony/storyblok/adapters.mdx                 | 4 ++--
 docs/php/symfony/storyblok/{ => api}/content-api.mdx    | 0
 docs/php/symfony/storyblok/{ => api}/management-api.mdx | 0
 4 files changed, 4 insertions(+), 4 deletions(-)
 rename docs/php/symfony/storyblok/{ => api}/content-api.mdx (100%)
 rename docs/php/symfony/storyblok/{ => api}/management-api.mdx (100%)

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index 0381b8a..f55b29b 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -25,8 +25,8 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 [2]: /docs/php/symfony/storyblok
 [3]: /docs/php/symfony/storyblok/cli
 [4]: /docs/php/symfony/storyblok/webhook
-[5]: /docs/php/symfony/storyblok/content-api
-[6]: /docs/php/symfony/storyblok/management-api
+[5]: /docs/php/symfony/storyblok/api/content-api
+[6]: /docs/php/symfony/storyblok/api/management-api
 [7]: /docs/php/symfony/storyblok/id-slug-mapper
 [8]: /docs/php/symfony/storyblok/request-validator
 [9]: /docs/php/symfony/storyblok/backend-edit-url-helper
diff --git a/docs/php/symfony/storyblok/adapters.mdx b/docs/php/symfony/storyblok/adapters.mdx
index c669f5e..dde10c3 100644
--- a/docs/php/symfony/storyblok/adapters.mdx
+++ b/docs/php/symfony/storyblok/adapters.mdx
@@ -107,7 +107,7 @@ On the adapter, you have access to different services for this specific Storyblo
 
 ### Content API
 
-[Content API docs](./content-api)
+[Content API docs](./api/content-api)
 
 Fetch and transform Storyblok content data (for example stories, links and space data).
 
@@ -117,7 +117,7 @@ $appStoryblok->contentApi
 
 ### Management API
 
-[Management API docs](./management-api)
+[Management API docs](./api/management-api)
 
 Manage your Storyblok space via the Management API, for example when syncing component definitions.
 
diff --git a/docs/php/symfony/storyblok/content-api.mdx b/docs/php/symfony/storyblok/api/content-api.mdx
similarity index 100%
rename from docs/php/symfony/storyblok/content-api.mdx
rename to docs/php/symfony/storyblok/api/content-api.mdx
diff --git a/docs/php/symfony/storyblok/management-api.mdx b/docs/php/symfony/storyblok/api/management-api.mdx
similarity index 100%
rename from docs/php/symfony/storyblok/management-api.mdx
rename to docs/php/symfony/storyblok/api/management-api.mdx

From 095eb424c2aaee4b3834aa9d43cd6eca66df38d4 Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 17:31:11 +0100
Subject: [PATCH 11/12] Finalize storyblok docs

---
 blog/2026-03-20-storyblok-adapters.mdx              | 11 +++++++----
 docs/php/symfony/storyblok/adapters.mdx             |  6 +++---
 docs/php/symfony/storyblok/api/content-api.mdx      |  4 ----
 docs/php/symfony/storyblok/api/management-api.mdx   |  6 +-----
 docs/php/symfony/storyblok/asset-proxy/index.mdx    |  4 ----
 docs/php/symfony/storyblok/cli.mdx                  |  4 ----
 docs/php/symfony/storyblok/components/index.mdx     |  4 ----
 .../symfony/storyblok/definitions-synced-event.mdx  |  4 ----
 docs/php/symfony/storyblok/image-focus.mdx          |  4 ----
 docs/php/symfony/storyblok/index.mdx                |  9 ++++++++-
 .../{ => more-features}/backend-edit-url-helper.mdx |  4 ----
 .../{ => more-features}/id-slug-mapper.mdx          |  4 ----
 docs/php/symfony/storyblok/more-features/index.mdx  | 13 +++++++++++++
 .../{ => more-features}/request-validator.mdx       |  4 ----
 14 files changed, 32 insertions(+), 49 deletions(-)
 rename docs/php/symfony/storyblok/{ => more-features}/backend-edit-url-helper.mdx (93%)
 rename docs/php/symfony/storyblok/{ => more-features}/id-slug-mapper.mdx (94%)
 create mode 100644 docs/php/symfony/storyblok/more-features/index.mdx
 rename docs/php/symfony/storyblok/{ => more-features}/request-validator.mdx (95%)

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index f55b29b..4ef87ec 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -12,13 +12,15 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 - Dedicated docs for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8].
 - New docs for [Backend Edit URL Helper][9], [Definitions Synced Event][10], and [Webhook Actions][11].
 - New [Asset Proxy][12] section with setup/configuration and usage details.
+- New [More Features][13] section for miscellaneous mostly-internal helper features.
 
 ## Updated Existing Pages
 
 - [Storyblok installation page][2] now reflects the adapter-based flow.
 - [CLI docs][3] now describe adapter-scoped commands and include the post-sync `StoryblokDefinitionsSyncedEvent` hook.
 - [Webhook docs][4] now use `AppStoryblokAdapter` examples and link to the webhook action mapping details.
-- [Storyblok index][2] now links to the new Asset Proxy section.
+- [Storyblok index][2] now links to the new Asset Proxy section and includes an events overview.
+- `More Features` was moved to the bottom of the Storyblok sidebar order.
 
 
 [1]: /docs/php/symfony/storyblok/adapters
@@ -27,9 +29,10 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 [4]: /docs/php/symfony/storyblok/webhook
 [5]: /docs/php/symfony/storyblok/api/content-api
 [6]: /docs/php/symfony/storyblok/api/management-api
-[7]: /docs/php/symfony/storyblok/id-slug-mapper
-[8]: /docs/php/symfony/storyblok/request-validator
-[9]: /docs/php/symfony/storyblok/backend-edit-url-helper
+[7]: /docs/php/symfony/storyblok/more-features/id-slug-mapper
+[8]: /docs/php/symfony/storyblok/more-features/request-validator
+[9]: /docs/php/symfony/storyblok/more-features/backend-edit-url-helper
 [10]: /docs/php/symfony/storyblok/definitions-synced-event
 [11]: /docs/php/symfony/storyblok/webhook-actions
 [12]: /docs/php/symfony/storyblok/asset-proxy
+[13]: /docs/php/symfony/storyblok/more-features
diff --git a/docs/php/symfony/storyblok/adapters.mdx b/docs/php/symfony/storyblok/adapters.mdx
index dde10c3..3d01e94 100644
--- a/docs/php/symfony/storyblok/adapters.mdx
+++ b/docs/php/symfony/storyblok/adapters.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: -1
 ---
 
 # Adapters
@@ -127,7 +127,7 @@ $appStoryblok->managementApi
 
 ### ID Slug Mapper
 
-[ID Slug Mapper docs](./id-slug-mapper)
+[ID Slug Mapper docs](./more-features/id-slug-mapper)
 
 Resolve between Story IDs and slugs using the content API.
 
@@ -137,7 +137,7 @@ $appStoryblok->idSlugMapper
 
 ### Request Validator
 
-[Request Validator docs](./request-validator)
+[Request Validator docs](./more-features/request-validator)
 
 Validate incoming webhook requests against your adapter webhook configuration.
 
diff --git a/docs/php/symfony/storyblok/api/content-api.mdx b/docs/php/symfony/storyblok/api/content-api.mdx
index b21e6ad..dee3a21 100644
--- a/docs/php/symfony/storyblok/api/content-api.mdx
+++ b/docs/php/symfony/storyblok/api/content-api.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 11
----
-
 # Content API
 
 The Content API is available on the adapter as:
diff --git a/docs/php/symfony/storyblok/api/management-api.mdx b/docs/php/symfony/storyblok/api/management-api.mdx
index fecad43..71612af 100644
--- a/docs/php/symfony/storyblok/api/management-api.mdx
+++ b/docs/php/symfony/storyblok/api/management-api.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 12
----
-
 # Management API
 
 The Management API is available on the adapter as:
@@ -136,5 +132,5 @@ $appStoryblok->managementApi->sendRequest("components");
 
 ## Deprecated
 
-`fetchFolderTitleMap()` and `fetchFoldersInPath()` are deprecated in `ManagementApi`.  
+`fetchFolderTitleMap()` and `fetchFoldersInPath()` are deprecated in `ManagementApi`.
 Use the Content API equivalents instead.
diff --git a/docs/php/symfony/storyblok/asset-proxy/index.mdx b/docs/php/symfony/storyblok/asset-proxy/index.mdx
index a513437..f820495 100644
--- a/docs/php/symfony/storyblok/asset-proxy/index.mdx
+++ b/docs/php/symfony/storyblok/asset-proxy/index.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 18
----
-
 # Asset Proxy
 
 The Storyblok Asset Proxy lets your application serve Storyblok assets through your own app URL.
diff --git a/docs/php/symfony/storyblok/cli.mdx b/docs/php/symfony/storyblok/cli.mdx
index 4825203..db0054e 100644
--- a/docs/php/symfony/storyblok/cli.mdx
+++ b/docs/php/symfony/storyblok/cli.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 20
----
-
 # CLI
 
 To integrate your local definitions with Storyblok, you need to push your config to their API.
diff --git a/docs/php/symfony/storyblok/components/index.mdx b/docs/php/symfony/storyblok/components/index.mdx
index 7d5b504..50e29b5 100644
--- a/docs/php/symfony/storyblok/components/index.mdx
+++ b/docs/php/symfony/storyblok/components/index.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 10
----
-
 # Components
 
 Storyblok works and looks like a virtual filesystem. You can have folders and documents inside of them.
diff --git a/docs/php/symfony/storyblok/definitions-synced-event.mdx b/docs/php/symfony/storyblok/definitions-synced-event.mdx
index 8d67eaf..70fa956 100644
--- a/docs/php/symfony/storyblok/definitions-synced-event.mdx
+++ b/docs/php/symfony/storyblok/definitions-synced-event.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 16
----
-
 # Definitions Synced Event
 
 After a successful `storyblok:definitions:sync`, the bundle dispatches `StoryblokDefinitionsSyncedEvent`.
diff --git a/docs/php/symfony/storyblok/image-focus.mdx b/docs/php/symfony/storyblok/image-focus.mdx
index b890dc3..9ddf3a5 100644
--- a/docs/php/symfony/storyblok/image-focus.mdx
+++ b/docs/php/symfony/storyblok/image-focus.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 100
----
-
 # Image Focus
 
 In Storyblok, you can set a focus point in a image.
diff --git a/docs/php/symfony/storyblok/index.mdx b/docs/php/symfony/storyblok/index.mdx
index c2cdba8..2829399 100644
--- a/docs/php/symfony/storyblok/index.mdx
+++ b/docs/php/symfony/storyblok/index.mdx
@@ -45,5 +45,12 @@ Continue with the [adapter guide](./adapters) for setup, usage and configuration
 
 ## Additional Helpers
 
-- [Backend Edit URL Helper](./backend-edit-url-helper)
 - [Asset Proxy](./asset-proxy)
+- [More Features](./more-features)
+
+## Events Overview
+
+The Storyblok bundle dispatches these events:
+
+- `StoryblokWebhookEvent` for incoming Storyblok webhooks ([Webhook docs](./webhook), [Webhook Actions](./webhook-actions)).
+- `StoryblokDefinitionsSyncedEvent` after successful component sync ([Definitions Synced Event](./definitions-synced-event)).
diff --git a/docs/php/symfony/storyblok/backend-edit-url-helper.mdx b/docs/php/symfony/storyblok/more-features/backend-edit-url-helper.mdx
similarity index 93%
rename from docs/php/symfony/storyblok/backend-edit-url-helper.mdx
rename to docs/php/symfony/storyblok/more-features/backend-edit-url-helper.mdx
index 7d42319..1bd709e 100644
--- a/docs/php/symfony/storyblok/backend-edit-url-helper.mdx
+++ b/docs/php/symfony/storyblok/more-features/backend-edit-url-helper.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 15
----
-
 # Backend Edit URL Helper
 
 `StoryblokBackendUrlGenerator` generates Storyblok backend edit links.
diff --git a/docs/php/symfony/storyblok/id-slug-mapper.mdx b/docs/php/symfony/storyblok/more-features/id-slug-mapper.mdx
similarity index 94%
rename from docs/php/symfony/storyblok/id-slug-mapper.mdx
rename to docs/php/symfony/storyblok/more-features/id-slug-mapper.mdx
index be52168..6924eec 100644
--- a/docs/php/symfony/storyblok/id-slug-mapper.mdx
+++ b/docs/php/symfony/storyblok/more-features/id-slug-mapper.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 13
----
-
 # ID Slug Mapper
 
 The ID Slug Mapper is available on the adapter as:
diff --git a/docs/php/symfony/storyblok/more-features/index.mdx b/docs/php/symfony/storyblok/more-features/index.mdx
new file mode 100644
index 0000000..8cddde9
--- /dev/null
+++ b/docs/php/symfony/storyblok/more-features/index.mdx
@@ -0,0 +1,13 @@
+---
+sidebar_position: 1000
+---
+
+# More Features
+
+These are miscellaneous Storyblok bundle features that are mainly used internally.
+
+In special cases, they can be used to implement custom requirements in your application.
+
+- [Backend Edit URL Helper](./backend-edit-url-helper)
+- [Request Validator](./request-validator)
+- [ID Slug Mapper](./id-slug-mapper)
diff --git a/docs/php/symfony/storyblok/request-validator.mdx b/docs/php/symfony/storyblok/more-features/request-validator.mdx
similarity index 95%
rename from docs/php/symfony/storyblok/request-validator.mdx
rename to docs/php/symfony/storyblok/more-features/request-validator.mdx
index e00a04f..b69ceaa 100644
--- a/docs/php/symfony/storyblok/request-validator.mdx
+++ b/docs/php/symfony/storyblok/more-features/request-validator.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 14
----
-
 # Request Validator
 
 The request validator is available on the adapter as:

From d414051ddccf486696c76f35613b93f35750a801 Mon Sep 17 00:00:00 2001
From: Jannik Zschiesche <j.zschiesche@21torr.com>
Date: Fri, 20 Mar 2026 17:35:27 +0100
Subject: [PATCH 12/12] Fix invalid links

---
 blog/2026-03-20-storyblok-adapters.mdx | 5 ++---
 docs/php/symfony/storyblok/index.mdx   | 2 +-
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/blog/2026-03-20-storyblok-adapters.mdx b/blog/2026-03-20-storyblok-adapters.mdx
index 4ef87ec..225a354 100644
--- a/blog/2026-03-20-storyblok-adapters.mdx
+++ b/blog/2026-03-20-storyblok-adapters.mdx
@@ -10,7 +10,7 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 
 - [Adapters guide][1] with setup, configuration and usage.
 - Dedicated docs for [Content API][5], [Management API][6], [ID Slug Mapper][7], and [Request Validator][8].
-- New docs for [Backend Edit URL Helper][9], [Definitions Synced Event][10], and [Webhook Actions][11].
+- New docs for [Backend Edit URL Helper][9] and [Definitions Synced Event][10].
 - New [Asset Proxy][12] section with setup/configuration and usage details.
 - New [More Features][13] section for miscellaneous mostly-internal helper features.
 
@@ -18,7 +18,7 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 
 - [Storyblok installation page][2] now reflects the adapter-based flow.
 - [CLI docs][3] now describe adapter-scoped commands and include the post-sync `StoryblokDefinitionsSyncedEvent` hook.
-- [Webhook docs][4] now use `AppStoryblokAdapter` examples and link to the webhook action mapping details.
+- [Webhook docs][4] now use `AppStoryblokAdapter` examples.
 - [Storyblok index][2] now links to the new Asset Proxy section and includes an events overview.
 - `More Features` was moved to the bottom of the Storyblok sidebar order.
 
@@ -33,6 +33,5 @@ The Storyblok docs now include a complete guide for the adapter-based setup.
 [8]: /docs/php/symfony/storyblok/more-features/request-validator
 [9]: /docs/php/symfony/storyblok/more-features/backend-edit-url-helper
 [10]: /docs/php/symfony/storyblok/definitions-synced-event
-[11]: /docs/php/symfony/storyblok/webhook-actions
 [12]: /docs/php/symfony/storyblok/asset-proxy
 [13]: /docs/php/symfony/storyblok/more-features
diff --git a/docs/php/symfony/storyblok/index.mdx b/docs/php/symfony/storyblok/index.mdx
index 2829399..3220ab2 100644
--- a/docs/php/symfony/storyblok/index.mdx
+++ b/docs/php/symfony/storyblok/index.mdx
@@ -52,5 +52,5 @@ Continue with the [adapter guide](./adapters) for setup, usage and configuration
 
 The Storyblok bundle dispatches these events:
 
-- `StoryblokWebhookEvent` for incoming Storyblok webhooks ([Webhook docs](./webhook), [Webhook Actions](./webhook-actions)).
+- `StoryblokWebhookEvent` for incoming Storyblok webhooks ([Webhook docs](./webhook)).
 - `StoryblokDefinitionsSyncedEvent` after successful component sync ([Definitions Synced Event](./definitions-synced-event)).