The VTEX Headless CMS API provides content management capabilities for FastStore and headless VTEX storefronts. It enables managing CMS pages, sections, content types, and building blocks that compose headless commerce experiences.
openapi: 3.0.0
info:
title: VTEX Headless CMS
description: "The [VTEX Headless CMS](https://www.faststore.dev/docs/headless-cms-overview) is a solution for storefront content management.\nYou can use the Headless CMS API to fetch data about your project's pages and content types, including `status`, `id`, and `type`. \r\n\r\n ## Index \r\n\r\n ### Pages \r\n- `GET` [Get all Content Types](https://developers.vtex.com/docs/api-reference/headless-cms-api#get-/_v/cms/api/-projectId-)\r\n- `GET` [Get all CMS pages by content type](https://developers.vtex.com/docs/api-reference/headless-cms-api#get-/_v/cms/api/-projectId-/-content-type-)\r\n- `GET` [Get CMS page](https://developers.vtex.com/docs/api-reference/headless-cms-api#get-/_v/cms/api/-projectId-/-content-type-/-document-id-)\n\n**Servers**\n- `https://{accountName}.myvtex.com/`\n- `https://{workspace}--{accountName}.myvtex.com/`\r\n\r\n## Common parameters\r\n\r\n| **Parameter name** | **Description** | **Type** |\r\n| --------------- | ----------------- | ----------------- |\r\n| {{accountName}} | Name of the VTEX account. Used as part of the URL. | Server variable. |\r\n| {{workspace}} | Name of the VTEX workspace. | Server variable. |\r\n| {{projectId}} | Project ID specified in the settings of the CMS (alpha) app. | Path variable. |\r\n\r\n"
version: 0.31.2
servers:
- url: https://{accountName}.myvtex.com
variables:
accountName:
default: storeframework
description: Name of the VTEX account. Used as part of the URL.
- url: https://{workspace}--{accountName}.myvtex.com
variables:
accountName:
default: storeframework
description: Name of the VTEX account. Used as part of the URL.
workspace:
default: test
description: Name of the VTEX workspace. Used as part of the URL.
paths:
/_v/cms/api/{projectId}:
get:
summary: VTex Get all content types
tags:
- Pages
description: "Retrieves data from all Content Types.\r\n\r\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| CMS | cms | **See CMS menu on the top-bar** |\n| CMS | cms | **Settings** |\n| CMS | GraphQL | **CMS GraphQL API** | \n\n There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add the resources above to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: GetAllContentTypes
parameters:
- name: projectId
in: path
description: Project ID specified in the settings of the CMS (alpha) app.
required: true
style: simple
schema:
type: string
example: faststore
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
description: Response body object.
type: object
properties:
contentTypes:
description: Array with data of each content type.
type: array
items:
description: Object with data of a specific content type.
type: object
properties:
id:
description: Content type identifier specified in the FastStore project.
type: string
name:
description: Content type name specified in the FastStore project.
type: string
configurationSchemaSets:
description: Array with data of the `configurationSchemaSets` tabs specified in the FastStore project.
type: array
items:
description: Object with data about a specific content type tab.
type: object
properties:
name:
description: Name of the content type tab.
type: string
configurations:
description: Custom configurations of the content type tab, which may vary based on the content type schema defined in the FastStore project.
type: array
items:
type: object
description: Object with custom configurations of the content type tab.
properties:
name:
description: Section of a form.
type: string
schema:
type: object
description: Customizable [JSON schema](https://json-schema.org/learn/getting-started-step-by-step).
required:
- title
- description
properties:
title:
type: string
description: Section title.
description:
type: string
description: Section description.
widget:
type: object
description: '[Widget](https://v1.faststore.dev/tutorials/cms-storecomponents/3#using-widgets) to be used in the UI. Should be filled with [`uiSchema`](https://react-jsonschema-form.readthedocs.io/en/docs/api-reference/uiSchema/) along with [`widgets`](https://react-jsonschema-form.readthedocs.io/en/docs/usage/widgets/) to specify which UI widget should be used to render a given field of your schema. The format should be `"{uiSchema}": "{widgetName}"`.'
additionalProperties: true
additionalProperties: true
example:
contentTypes:
- id: home
name: Home Page
configurationSchemaSets: []
- id: plp
name: PLP
configurationSchemaSets:
- name: Parameters
configurations:
- name: Collection
schema:
title: Collection
description: Definition of a Collection for the CMS.
oneOf:
- title: Category
description: Configure a Category.
type: object
required:
- categoryId
- sort
properties:
categoryId:
title: Category ID
description: Category identifier to organize the store's products.
type: string
sort:
title: Default ordering
description: Organizes and displays a set of products based on filters.
type: string
default: '""'
enum:
- '""'
- discount:desc
- release:desc
- name:asc
- name:desc
- orders:desc
- price:asc
- price:desc
enumNames:
- Relevance
- Discount
- Release date
- Name, ascending
- Name, descending
- Sales
- 'Price: Low to High'
- 'Price: High to Low'
- title: Brand
description: Configure a brand page.
type: object
required:
- brandId
- sort
properties:
brandId:
title: Brand ID
description: Brand identifier to categorize a group of products.
type: string
sort:
title: Default ordering
description: Organizes and displays a set of products based on filters.
type: string
enum:
- '""'
- discount:desc
- release:desc
- name:asc
- name:desc
- orders:desc
- price:asc
- price:desc
enumNames:
- Relevance
- Discount
- Release date
- Name, ascending
- Name, descending
- Sales
- 'Price: Low to High'
- 'Price: High to Low'
- title: Collection
description: Configure a collection page.
type: object
required:
- clusterId
- sort
- seo
properties:
clusterId:
title: Collection ID
description: Collection identifier to categorize a group of products.
type: string
sort:
title: Default ordering
description: Organizes and displays a set of products based on filters.
type: string
default: '""'
enum:
- '""'
- discount:desc
- release:desc
- name:asc
- name:desc
- orders:desc
- price:asc
- price:desc
enumNames:
- Relevance
- Discount
- Release date
- Name, ascending
- Name, descending
- Sales
- 'Price: Low to High'
- 'Price: High to Low'
seo:
type: object
title: Seo
description: Search Engine Optimization options.
widget:
ui:ObjectFieldTemplate: GoogleSeoPreview
required:
- title
- description
- slug
properties:
title:
type: string
title: Title
description: Title that appears in the browser tab and is suggested for search engines.
default: Page title
slug:
type: string
title: URL slug
description: Final part of the page's address. No spaces allowed.
default: /path/to/page
pattern: ^/([a-zA-Z0-9]|-|/|_)*
description:
type: string
title: Description (Meta description)
description: Suggested meta description for search engines.
default: Page description
- id: institutionalPage
name: Institutional page
configurationSchemaSets:
- name: SEO
configurations:
- name: siteMetadataWithSlug
schema:
title: Site Metadata
description: Configure global site metadata.
type: object
widget:
ui:ObjectFieldTemplate: GoogleSeoPreview
properties:
title:
title: Default page title
description: Display this title when no other title is available.
type: string
default: Store Theme | VTEX FastStore
description:
title: Meta tag description
description: Meta tag description. A HTML tag that provides a concise summary of a web page.
type: string
default: A beautifully designed site for general VTEX stores.
titleTemplate:
title: Title template
description: Title template to be used in category/product pages.
type: string
default: '%s | Store Theme'
slug:
title: URL Slug
description: Part of the URL to identify a particular page or product.
type: string
default: /landing-page-url
'404':
description: Not Found
headers: {}
content:
application/json:
schema:
type: object
description: Response body object.
properties:
code:
type: string
description: Error type code.
message:
type: string
description: Error message.
source:
type: string
description: Error source.
requestId:
type: string
description: VTEX request identifier.
example:
code: NotFound
message: storeframework.myvtex.com.br not found
source: Vtex.Kube.Router.WebApi
requestId: b49522afa7c94b76885450f652be7bfc
'500':
description: Internal Server Error
headers: {}
content: {}
deprecated: false
/_v/cms/api/{projectId}/{content-type}:
get:
summary: VTex Get all CMS pages by content type
tags:
- Pages
description: "Gets data from all pages of a given content type.\r\n\r\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| CMS | cms | **See CMS menu on the top-bar** |\n| CMS | cms | **Settings** |\n| CMS | GraphQL | **CMS GraphQL API** | \n\n There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add the resources above to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: GetPagesbyContentType
parameters:
- name: projectId
in: path
description: Project ID specified in the settings of the CMS (alpha) app.
required: true
style: simple
schema:
type: string
example: faststore
- name: content-type
in: path
description: Content type identifier defined in the FastStore project.
required: true
style: simple
schema:
type: string
example: plp
- name: versionId
in: query
description: Version ID presented in the URL path of a CMS preview.
style: form
explode: true
schema:
type: string
example: e7263fc8-bc68-4052-9e25-dd5a2572d3bb
- name: releaseId
in: query
description: Release ID presented in the URL path of a CMS preview.
style: form
explode: true
schema:
type: string
example: 6196c277c6dce15f9709a2a7
- name: filters[{field}]
in: query
description: |-
Filter results by a property of the page (e.g., `filters[status]`) or by a nested custom field of the `parameters` object (e.g., `filters[parameters.collection.sort]`).
*Replace {field} with the desired property.*
style: form
explode: true
schema:
type: string
example: published
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
hasNextPage:
description: Indicates if there are more items to fetch.
type: boolean
totalItems:
description: Total number of results.
type: integer
data:
description: Array with data from all pages of the given content type.
type: array
items:
description: Object with data from a specific page.
type: object
properties:
id:
description: Document ID presented in the URL path of a CMS preview.
type: string
name:
description: Name of the page created via the CMS interface.
type: string
type:
description: Name of the content type defined in the FastStore project.
type: string
status:
description: Current status of the page.
type: string
versionId:
description: Version ID.
type: string
versionStatus:
description: Version status.
type: string
sections:
description: Sections that compose the page.
type: array
items:
description: Object with data about a specific section.
type: object
properties:
id:
description: Section ID.
type: string
name:
description: Section name.
type: string
data:
description: Custom field values of the Section. Varies depending on the Section schema defined in the FastStore project.
type: object
parameters:
description: Object with the configuration values of a `configurationSchemaSets` tab. Varies depending on the content type schema defined in the FastStore project.
type: object
example:
hasNextPage: false
totalItems: 2
data:
- id: d05d3db8-62b2-4f0b-9b70-d6d25ff29b6e
name: Electronics
type: plp
status: published
versionId: ed51d1cd-e020-4f16-b48b-ca83e720472d
versionStatus: published
sections:
- id: '1632244409269'
name: RichText
data:
content: '{"blocks":[{"key":"dtg7g","text":"-","type":"unstyled","depth":0,"inlineStyleRanges":[],"entityRanges":[],"data":{}}],"entityMap":{}}'
- id: '1632244445091'
name: RichText
data:
content: '{"blocks":[{"key":"2qtft","text":",","type":"unstyled","depth":0,"inlineStyleRanges":[],"entityRanges":[],"data":{}}],"entityMap":{}}'
parameters:
collection:
sort: '""'
brandId: '123'
- id: 4ab6388d-79e6-492f-adda-3e251b85eeb6
name: Beauty
type: plp
status: published
versionId: 95f940d4-584e-4b3d-9872-8c713ba42583
versionStatus: published
sections:
- id: '1643319987751'
name: SearchBanner
data:
desktop:
srcSet: https://storecomponents.vtexassets.com/assets/vtex.file-manager-graphql/images/dda7c17e-5182-4439-b5af-94f651e2d835___1ef09be73ec9e80c719da13432666441.jpeg
mobile:
srcSet: https://storecomponents.vtexassets.com/assets/vtex.file-manager-graphql/images/ed8ef334-c1e5-4269-8728-34dbffeda424___1ef09be73ec9e80c719da13432666441.jpeg
title: beauty
description: beauty products
alt: beauty
parameters:
collection:
sort: '""'
seo:
title: Page title
slug: /beauty
description: beauty products
clusterId: '1182'
'404':
description: Not Found
headers: {}
content:
application/json:
schema:
type: object
description: Response body object.
properties:
code:
type: string
description: Error type code.
message:
type: string
description: Error message.
source:
type: string
description: Error source.
requestId:
type: string
description: VTEX request identifier.
example:
code: NotFound
message: storeframework.myvtex.com.br not found
source: Vtex.Kube.Router.WebApi
requestId: b49522afa7c94b76885450f652be7bfc
'500':
description: Internal Server Error
headers: {}
content: {}
deprecated: false
/_v/cms/api/{projectId}/{content-type}/{document-id}:
get:
summary: VTex Get CMS page
tags:
- Pages
description: "Gets all data from a given page.\r\n\r\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| CMS | cms | **See CMS menu on the top-bar** |\n| CMS | cms | **Settings** |\n| CMS | GraphQL | **CMS GraphQL API** | \n\n There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add the resources above to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: GetCMSpage
parameters:
- name: projectId
in: path
description: Project ID specified in the settings of the CMS (alpha) app.
required: true
style: simple
schema:
type: string
example: faststore
- name: content-type
in: path
description: Content type ID defined in the FastStore project.
required: true
style: simple
schema:
type: string
example: plp
- name: document-id
in: path
description: Document ID presented in the URL path of a CMS preview.
required: true
style: simple
schema:
type: string
example: 5af643b5-9a6d-48f2-9b34-919dd762c908
- name: versionId
in: query
description: Version ID presented in the URL path of a CMS preview.
style: form
explode: true
schema:
type: string
example: e7263fc8-bc68-4052-9e25-dd5a2572d3bb
- name: releaseId
in: query
description: Release ID presented in the URL path of a CMS preview.
style: form
explode: true
schema:
type: string
example: 6196c277c6dce15f9709a2a7
responses:
'200':
description: OK
headers: {}
content:
application/json:
example:
id: ad2fd81d-a53c-4281-8d01-a4fc2f274db3
name: Home
type: home
status: published
versionId: e3867e2c-7082-4fe6-83ed-c473242b6970
versionStatus: publishing
sections:
- id: '1651804180614'
name: Alert
data:
dismissible: true
icon: Bell
text: alert text
linkText: alert link
actionLink: link.url.com
- id: '1647286556072'
name: Hero
data:
imageSrc: https://storeframework.vtexassets.com/assets/vtex.file-manager-graphql/images/299f7d32-bb6a-40fd-82a0-4af5573ba572___17239443c00c1e894cff10ca05018058.jpg
title: New Products Available
subtitle: At FastStore you can shop the best tech of 2022. Enjoy and get 10% off on your first purchase.
linkText: See all
link: /office
imageAlt: hero image
- id: '1649293076336'
name: ProductShelf
data:
first: 5
after: '0'
sort: score_desc
selectedFacets:
- key: productClusterIds
value: '140'
title: Most Wanted!
- id: '1649293548351'
name: ProductTiles
data:
first: 3
after: '0'
sort: score_desc
selectedFacets:
- key: productClusterIds
value: '141'
title: Just Arrived
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-headless-cms-openapi-original.yml