{"openapi":"3.1.0","info":{"title":"Beta 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\n\n| UI Name | Permission | Parameter |\n|:--------|:-----------|:----------|\n| Add scopes ++++ | modify | `...` |\n| Add | read-only | `store_v2_marketing_read_only` |\n\n### Authentication header\n\n| Header | Argument | Description |\n|:-------|:---------|:------------|\n| `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). |\n\n### Further reading\n\nFor example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).\n\nFor more about BigCommerce OAuth scopes, see [API Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).\n\nFor 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\n\n| UI Name | Permission | Parameter |\n|:--------|:-----------|:----------|\n| Add scopes ++++ | modify | `...` |\n| Add | read-only | `store_v2_marketing_read_only` |\n\n### Authentication header\n\n| Header | Argument | Description |\n|:-------|:---------|:------------|\n| `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). |\n\n### Further reading\n\nFor example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).\n\nFor more about BigCommerce OAuth scopes, see [API Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).\n\nFor 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.\n"},"current":{"type":"string","description":"Link to the current page returned in the response.\n"},"next":{"type":"string","description":"Link to the next page returned in the response.\n"}},"description":"Pagination links for the previous and next parts of the whole collection.\n","title":"PaginationLinks"},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items in the result set.\n"},"count":{"type":"integer","description":"Total number of items in the collection response.\n"},"per_page":{"type":"integer","description":"The amount of items returned in the collection per page, controlled by the limit parameter.\n"},"current_page":{"type":"integer","description":"The page you are currently on within the collection.\n"},"total_pages":{"type":"integer","description":"The total number of pages in the collection.\n"},"links":{"$ref":"#/components/schemas/PaginationLinks","description":"Pagination links for the previous and next parts of the whole collection.\n"}},"description":"Data about the response, including pagination and collection totals.\n","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.\n"},"title":{"type":"string","description":"The error title describing the particular error.\n"},"type":{"type":"string"},"instance":{"type":"string"},"errors":{"$ref":"#/components/schemas/DetailedErrors"}},"description":"Error payload for the BigCommerce API.\n","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\n\n| UI Name | Permission | Parameter |\n|:--------|:-----------|:----------|\n| Add scopes ++++ | modify | `...` |\n| Add | read-only | `store_v2_marketing_read_only` |\n\n### Authentication header\n\n| Header | Argument | Description |\n|:-------|:---------|:------------|\n| `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). |\n\n### Further reading\n\nFor example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).\n\nFor more about BigCommerce OAuth scopes, see [API Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).\n\nFor a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes)."}}}}