openapi: 3.1.0
info:
  title: 'Admin Content: Page Widgets'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/content/page-widgets:
    get:
      operationId: getPageWidgets
      summary: Get Page Snapshot
      description: Get a snapshot of all the page widget regions for a given channel, template file, or entity.
      tags:
        - pageWidgets
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: channel_id
          in: query
          description: >-
            The ID of the channel for which you want to retrieve page widgets. Defaults to the first channel created on
            the store.
          required: false
          schema:
            type: integer
            default: 1
        - name: template_file
          in: query
          description: The template file that you would like to target. Leave it empty if the request is for Global regions.
          required: false
          schema:
            type: string
        - name: entity_id
          in: query
          description: >-
            The identifier of a page you would like to target. For product pages, choose product ID. For category pages,
            choose category ID. Home page does not support `entity_id`. Leave empty if the request is for global
            regions.
          required: false
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            | Add scopes ++++ | modify | `...` |

            | Add | read-only | `store_v2_marketing_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate access tokens, see [API
            Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see [API Accounts and OAuth
            Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
        - name: X-Correlation-Id
          in: header
          description: >-
            An identifier unique to a set of related requests. For use on headless storefronts, excluding BigCommerce
            for WordPress. For more information, see [Best
            Practices](/developer/docs/storefront/headless#correlating-requests) or the [Headless
            Guide](/developer/docs/storefront/headless#correlating-requests).
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page Widgets_getPageWidgets_Response_200'
        '422':
          description: Failure due to an invalid query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createPageWidgets
      summary: Publish or Overwrite Page Content
      description: Publish or overwrite the content of a page that uses page widgets.
      tags:
        - pageWidgets
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            | Add scopes ++++ | modify | `...` |

            | Add | read-only | `store_v2_marketing_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate access tokens, see [API
            Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see [API Accounts and OAuth
            Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
        - name: X-Correlation-Id
          in: header
          description: >-
            An identifier unique to a set of related requests. For use on headless storefronts, excluding BigCommerce
            for WordPress. For more information, see [Best
            Practices](/developer/docs/storefront/headless#correlating-requests) or the [Headless
            Guide](/developer/docs/storefront/headless#correlating-requests).
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: The request was successful. No response body is returned.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: The request payload was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/publish'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    LayoutConfiguration:
      type: object
      properties: {}
      description: JSON object of necessary configuration to construct a layout.
      title: LayoutConfiguration
    DropzoneConfiguration:
      type: object
      properties: {}
      description: JSON object of necessary configuration to construct a dropzone.
      title: DropzoneConfiguration
    WidgetConfiguration:
      type: object
      properties: {}
      description: JSON object of necessary configuration to construct a widget.
      title: WidgetConfiguration
    WidgetStorefrontApiQueryParams:
      type: object
      properties: {}
      description: >-
        A set of parameters used to query the GraphQL Storefront API. Used when the parent widget template is configured
        to request data directly from the GraphQL Storefront API; in this case, the parent widget template has the
        `storefront_api_query` property.
      title: WidgetStorefrontApiQueryParams
    WidgetType:
      type: string
      enum:
        - widget
      title: WidgetType
    widget:
      type: object
      properties:
        widget_template_uuid:
          type: string
          format: uuid
          description: >-
            The unique identifier of the parent widget template; set by the store or channel where the widget template
            originated.
        configuration:
          $ref: '#/components/schemas/WidgetConfiguration'
          description: JSON object of necessary configuration to construct a widget.
        storefront_api_query_params:
          $ref: '#/components/schemas/WidgetStorefrontApiQueryParams'
          description: >-
            A set of parameters used to query the GraphQL Storefront API. Used when the parent widget template is
            configured to request data directly from the GraphQL Storefront API; in this case, the parent widget
            template has the `storefront_api_query` property.
        name:
          type: string
          description: >-
            A human-readable label for the widget. Retrievable using either the [Get a
            widget](/developer/api-reference/rest/admin/content/widgets/widget/get-widget) or the [Get all
            widgets](/developer/api-reference/rest/admin/content/widgets/widget/get-widgets) endpoint.
        description:
          type: string
          description: >-
            A description of the widget. Retrievable using either the [Get a
            widget](/developer/api-reference/rest/admin/content/widgets/widget/get-widget) or the [Get all
            widgets](/developer/api-reference/rest/admin/content/widgets/widget/get-widgets) endpoint.
        type:
          $ref: '#/components/schemas/WidgetType'
      title: widget
    dropzone:
      type: object
      properties:
        configuration:
          $ref: '#/components/schemas/DropzoneConfiguration'
          description: JSON object of necessary configuration to construct a dropzone.
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/widget'
          description: Consists of [widget](#widgets) objects.
      title: dropzone
    LayoutType:
      type: string
      enum:
        - layout
      title: LayoutType
    layout:
      type: object
      properties:
        layout_template_uuid:
          type: string
          format: uuid
          description: Set by BigCommerce. Read-only.
        configuration:
          $ref: '#/components/schemas/LayoutConfiguration'
          description: JSON object of necessary configuration to construct a layout.
        name:
          type: string
          description: A human-readable label for the layout; displays in Page Builder.
        dropzones:
          type: array
          items:
            $ref: '#/components/schemas/dropzone'
          description: Consists of dropzone objects.
        type:
          $ref: '#/components/schemas/LayoutType'
      title: layout
    RegionChildrenItems:
      oneOf:
        - $ref: '#/components/schemas/layout'
        - $ref: '#/components/schemas/widget'
      title: RegionChildrenItems
    region:
      type: object
      properties:
        name:
          type: string
          description: Matches the name specified as `{{{region_name="..."}}}` in a theme template file.
        children:
          type: array
          items:
            $ref: '#/components/schemas/RegionChildrenItems'
          description: Consists of layout and widget objects.
      title: region
    ContentPageWidgetsGetResponsesContentApplicationJsonSchemaData:
      type: object
      properties:
        regions:
          type: array
          items:
            $ref: '#/components/schemas/region'
      title: ContentPageWidgetsGetResponsesContentApplicationJsonSchemaData
    PaginationLinks:
      type: object
      properties:
        previous:
          type: string
          description: |
            Link to the previous page returned in the response.
        current:
          type: string
          description: |
            Link to the current page returned in the response.
        next:
          type: string
          description: |
            Link to the next page returned in the response.
      description: |
        Pagination links for the previous and next parts of the whole collection.
      title: PaginationLinks
    pagination:
      type: object
      properties:
        total:
          type: integer
          description: |
            Total number of items in the result set.
        count:
          type: integer
          description: |
            Total number of items in the collection response.
        per_page:
          type: integer
          description: |
            The amount of items returned in the collection per page, controlled by the limit parameter.
        current_page:
          type: integer
          description: |
            The page you are currently on within the collection.
        total_pages:
          type: integer
          description: |
            The total number of pages in the collection.
        links:
          $ref: '#/components/schemas/PaginationLinks'
          description: |
            Pagination links for the previous and next parts of the whole collection.
      description: |
        Data about the response, including pagination and collection totals.
      title: pagination
    metaCollection:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/pagination'
      description: Data about the response, including pagination and collection totals.
      title: metaCollection
    Page Widgets_getPageWidgets_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ContentPageWidgetsGetResponsesContentApplicationJsonSchemaData'
        meta:
          $ref: '#/components/schemas/metaCollection'
      title: Page Widgets_getPageWidgets_Response_200
    DetailedErrors:
      type: object
      properties: {}
      title: DetailedErrors
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code.
        title:
          type: string
          description: |
            The error title describing the particular error.
        type:
          type: string
        instance:
          type: string
        errors:
          $ref: '#/components/schemas/DetailedErrors'
      description: |
        Error payload for the BigCommerce API.
      title: ErrorResponse
    publish:
      type: object
      properties:
        regions:
          type: array
          items:
            $ref: '#/components/schemas/region'
        template_file:
          type: string
          description: The template file that you would like to target. Leave it empty if the request is for Global regions.
        entity_id:
          type: string
          description: >-
            The identifier of a page you would like to target. For product pages, choose product ID. For category pages,
            choose category ID. Home page does not support `entity_id`. Leave it empty if the request is for Global
            regions.
        channel_id:
          type: integer
          description: The id of the channel on which to create this placement. Defaults to the first channel created on the store.
      required:
        - regions
      title: publish
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--------|:-----------|:----------|

        | Add scopes ++++ | modify | `...` |

        | Add | read-only | `store_v2_marketing_read_only` |


        ### Authentication header


        | Header | Argument | Description |

        |:-------|:---------|:------------|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate access tokens, see [API Accounts
        and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts).


        For more about BigCommerce OAuth scopes, see [API Accounts and OAuth
        Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
