VTEX Headless CMS API

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 Specification

vtex-headless-cms-openapi-original.yml Raw ↑
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