key option or store it on the account; Storyblok expects the raw token in the Authorization header, with no Bearer prefix.
Two more settings are needed because every Management API route is scoped to one space on one regional host:
spaceId: the numeric space id.spaces.listis the way to find it.region:eu,us,ca,aporcn, matching where the space is hosted. It defaults toeu. A space only answers on its own host, and asking the wrong one looks like a missing space rather than a configuration mistake.
space_id and region.
Things to know before you write:
- Publishing is a GET.
stories.publishandstories.unpublishare served as GETs but change published state, so both are writes here. A retry of either repeats the state change. stories.listomits content. The list route returns stories without theircontentfield. Passwith_summaryfor a summary, or read the story withstories.get.contentis the schema’s own JSON. A story’s content is one object per component field, with acomponentkey naming the content type. The plugin passes it through untyped rather than guessing at a shape that depends on each project’s components.- Components are field schemas. Editing a component changes the shape every story of that type is parsed against, and a removed field’s values stay in existing stories, hidden from the editor, until a migration removes them.
- Asset writes are metadata only.
assets.updatechanges alt text, title, copyright, focus point, privacy and the publish window. Uploading new bytes uses a separate signed-upload flow that this plugin does not wrap. - Webhook actions come from the API.
webhooks.listActionsreads the accepted action names rather than hardcoding them, because Storyblok adds events over time. - Paging totals are in headers. Storyblok reports
totalandper_pageas response headers, which this client cannot return alongside the body, so page until an array comes back short or empty. - Some writes answer 204. Updating a tag, a datasource entry or an asset, and deleting a tag, a datasource or a datasource entry, return no body. Those updates return what was sent; those deletes return
{ id, deleted: true }. - Releases need an enterprise plan (Premium or Elite). On Starter, Growth and Growth Plus, the trial included,
releases.create,releases.get,releases.updateandreleases.deleteanswer 422 “This feature is available on Enterprise plans”;releases.liststill works and returns an empty list. - Rate limits are plan-based, 3 requests per second on Starter and 6 on paid plans, with a 429 to back off on.
- 43 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Storyblok API key before the first call: More: API Key
pnpm corsair setup --plugin=storyblok --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
List published stories under a slug prefixWhat’s next
API reference
Every
storyblok.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.