ButterCMS vs Storyblok

ButterCMS

The Read and Write APIs have a public OpenAPI 3.1 file, Markdown docs and a status page with no incident since October 2025. The Write API is a paid add-on from the $249 plan, capped at 2,000 or 5,000 calls a month. Writes answer 202 with no identifier, support rotates tokens, and the terms are an undated website document.

Storyblok

The hosted MCP server covers the whole Management API with seven tools, OAuth scopes split into read, write and publish per space, and a confirmation step on deletes. The Management API has no public OpenAPI spec, no idempotency keys and no monitor on the public status page, and publishing is a GET request.

ButterCMS

1. End every path with a slash. A missing slash returns a 301, and the vendor counts the redirect and the retry as two API calls
2. Send the write token only as Authorization: Token <token>. The auth_token query parameter works for reads only
3. On page creation send every field key of the page type, with empty strings for fields left blank
4. A 202 means queued, not saved. Read the entry back with preview=1 to confirm, and check a slug exists before retrying a create
5. Call the REST API directly for writes. The JavaScript SDK 3.0.3 has list, retrieve and search methods only

Storyblok

1. Pick the base URL by the space's region (mapi.storyblok.com for the EU, api-us, api-ca or api-ap otherwise). A token sent to the wrong region fails
2. Create stories without publish to keep them as drafts, then call the publish endpoint. It is a GET, so never prefetch or blindly retry it
3. Write translations as field__i18n__<code> keys inside the same content object, and set the component field to translatable first
4. Upload an asset in three steps (signed response, POST to S3, finish upload). Through MCP the S3 step needs shell access for curl
5. Stay under 3 calls a second on Starter and 6 on paid plans, and back off exponentially on 429. Saves that break a field's max_length return 422