{"openapi":"3.1.0","info":{"title":"Storyblok (BYOK) API","version":"0.1.0","description":"Storyblok (BYOK) lets an AI assistant read your own Storyblok data through the Storyblok API with a key you supply (Content Delivery API access token (public or preview)). Read-only: 8 tools (get_space, list_stories, get_story, list_links, list_tags, list_datasources, list_datasource_entries, list_taxonomies). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-storyblok.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-storyblok/docs"},"termsOfService":"https://connectorbay.com/byok-storyblok/terms"},"servers":[{"url":"https://byok-storyblok.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-storyblok/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_space":{"post":{"operationId":"get_space","summary":"Show the space the token belongs to: id, name, domain, languages and the cached-version timestamp. Use for \"What is the ","description":"Show the space the token belongs to: id, name, domain, languages and the cached-version timestamp. Use for \"What is the name and which languages does my Storyblok space have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"},"version":{"anyOf":[{"enum":["draft","published"],"type":"string"},{"type":"null"}],"default":"published","description":"Which content to read: 'published' (default, needs any token) or 'draft' (needs a preview token).","title":"Version"}},"required":["region"],"title":"get_spaceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_stories":{"post":{"operationId":"list_stories","summary":"List stories (entries) of the space with name, slugs, publish dates and tags, without their content. Newest-first order ","description":"List stories (entries) of the space with name, slugs, publish dates and tags, without their content. Newest-first order is not guaranteed; use sort_by. Use for \"Which stories are in the blog folder of my Storyblok space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"},"version":{"anyOf":[{"enum":["draft","published"],"type":"string"},{"type":"null"}],"default":"published","description":"Which content to read: 'published' (default, needs any token) or 'draft' (needs a preview token).","title":"Version"},"starts_with":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only stories whose full slug starts with this text, for example 'blog/'.","title":"Starts With"},"search_term":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to find in story names, slugs and content.","title":"Search Term"},"content_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only stories of this content type, for example 'page'.","title":"Content Type"},"with_tag":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only stories with this tag slug.","title":"With Tag"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by with an optional direction, for example 'created_at:desc' or 'name:asc'.","title":"Sort By"},"excluding_fields":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated content fields to leave out of each story.","title":"Excluding Fields"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 1000).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["region"],"title":"list_storiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_story":{"post":{"operationId":"get_story","summary":"Get one story with its fields (content), slugs, dates and tags. The story is identified by id, uuid or full slug. Use fo","description":"Get one story with its fields (content), slugs, dates and tags. The story is identified by id, uuid or full slug. Use for \"Show the story with full slug blog/hello-world in my Storyblok space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"},"id":{"description":"The story's numeric id, its uuid (then set find_by to 'uuid') or its full slug such as 'blog/hello-world'.","maxLength":200,"title":"Id","type":"string"},"find_by":{"anyOf":[{"const":"uuid","type":"string"},{"type":"null"}],"default":null,"description":"Set to 'uuid' when the story is identified by uuid.","title":"Find By"},"version":{"anyOf":[{"enum":["draft","published"],"type":"string"},{"type":"null"}],"default":"published","description":"Which content to read: 'published' (default, needs any token) or 'draft' (needs a preview token).","title":"Version"},"language":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Language code of the translation to return, for example 'de'.","title":"Language"},"excluding_fields":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated content fields to leave out.","title":"Excluding Fields"}},"required":["region","id"],"title":"get_storyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_links":{"post":{"operationId":"list_links","summary":"List stories and folders as light link records (id, name, slug, folder flag, publish state), keyed by uuid. Useful for s","description":"List stories and folders as light link records (id, name, slug, folder flag, publish state), keyed by uuid. Useful for site trees. Use for \"Show the folder and page tree of my Storyblok space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"},"version":{"anyOf":[{"enum":["draft","published"],"type":"string"},{"type":"null"}],"default":"published","description":"Which content to read: 'published' (default, needs any token) or 'draft' (needs a preview token).","title":"Version"},"starts_with":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only links whose full slug starts with this text.","title":"Starts With"},"with_parent":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Folder id to list the children of; 0 lists items outside any folder.","title":"With Parent"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many items to return (1 to 1000).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["region"],"title":"list_linksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List the tags used on stories with the number of stories carrying each tag. Use for \"Which tags are used in my Storyblok","description":"List the tags used on stories with the number of stories carrying each tag. Use for \"Which tags are used in my Storyblok space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"},"version":{"anyOf":[{"enum":["draft","published"],"type":"string"},{"type":"null"}],"default":"published","description":"Which content to read: 'published' (default, needs any token) or 'draft' (needs a preview token).","title":"Version"},"starts_with":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only count stories whose full slug starts with this text.","title":"Starts With"}},"required":["region"],"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_datasources":{"post":{"operationId":"list_datasources","summary":"List the data sources (key-value lists such as translations or colours) with id, name, slug and dimensions. Use for \"Whi","description":"List the data sources (key-value lists such as translations or colours) with id, name, slug and dimensions. Use for \"Which data sources exist in my Storyblok space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to search data source names for.","title":"Search"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 1000).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["region"],"title":"list_datasourcesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_datasource_entries":{"post":{"operationId":"list_datasource_entries","summary":"List the entries (name and value pairs) of a data source, optionally in one dimension. Use for \"Show the entries of the ","description":"List the entries (name and value pairs) of a data source, optionally in one dimension. Use for \"Show the entries of the data source background-color in my Storyblok space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"},"datasource":{"description":"Slug of the data source, for example 'background-color'.","maxLength":200,"title":"Datasource","type":"string"},"dimension":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Dimension name to return values for.","title":"Dimension"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 1000).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["region","datasource"],"title":"list_datasource_entriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_taxonomies":{"post":{"operationId":"list_taxonomies","summary":"List the taxonomy terms defined in the space. Use for \"What taxonomies are defined in my Storyblok space\".","description":"List the taxonomy terms defined in the space. Use for \"What taxonomies are defined in my Storyblok space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Host label of the space's region: 'api' (EU), 'api-us' (United States) or 'api-ca' (Canada).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Region","type":"string"}},"required":["region"],"title":"list_taxonomiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}