Storyblok

Storyblok differentiates with its visual editing experience — editors see real-time visual previews while editing content, which is unique among headless CMS platforms. For agents, the API provides content delivery (CDN-cached reads) and management (CRUD) access. The content model uses 'components' (bloks) that are composable and nestable — content is built from a hierarchy of reusable components rather than flat content types. For agents managing content programmatically, the component model means content structures can be deeply nested. The Management API covers stories (content entries), components (schema definitions), assets, spaces, and collaborators. Multi-language content uses a dimension-based approach. The visual editing experience doesn't directly affect agent API usage but influences the content structures agents work with.

Content Delivery API uses access tokens (preview or public) passed via token query parameter. Management API uses personal access tokens via Authorization header. Preview tokens access draft content; public tokens access published content only. Management tokens are per-user with the user's role permissions. No fine-grained token scoping beyond the preview/public and management distinction. OAuth is available for app integrations. For agents, using public tokens for published content reads and management tokens for content operations provides clean separation. Token rotation requires generating new tokens. The auth model is straightforward and similar to Contentful's delivery/management token split.

Documentation at storyblok.com/docs covers API reference, framework-specific guides (Next.js, Nuxt, Gatsby, SvelteKit, Astro), and content management guides. The API reference covers Content Delivery and Management APIs with examples. Framework integration guides show how to connect Storyblok's visual editor with frontend frameworks. SDKs: JavaScript SDK (@storyblok/js), framework-specific packages. The documentation emphasizes visual editing setup — significant portions cover the editor integration rather than API usage. For agents focused on API-only content management, the Management API reference and content model documentation are the key resources. Community resources include a forum and Discord. The documentation is adequate but navigation can be challenging.

Content Delivery API (CDN) at api.storyblok.com/v2/cdn/stories. Story retrieval by slug or UUID. Filtering by content type, tags, dates, and custom fields. Resolve relations and links for connected content. Management API at mapi.storyblok.com/v1/spaces/{space_id}/ for story CRUD, component management, asset upload, and space configuration. Stories contain a content object following the component schema — deeply nested JSON structures. The content structure uses blocks (body) containing component instances. Pagination uses page/per_page parameters. Webhooks for story published/unpublished events. The API design is functional with some Storyblok-specific patterns: the content.body array of component blocks is more complex to construct than flat content models. Datasources provide reusable option lists.

API errors return JSON with status and error message. Standard HTTP status codes. CDN rate limits are generous for content delivery reads. Management API rate limits: per-space with plan-based thresholds. Story publishing validation ensures component schema compliance. Asset upload errors include file size and type validation messages. The CDN caching layer handles read scaling — published content is served from edge locations. Cache invalidation occurs on publish. The main consideration for agents: the nested component structure means content creation requests can be complex — validation errors for deeply nested structures can be difficult to debug. Management API retries should use exponential backoff.