BigCommerce Pages (Single) API

openapi: 3.2.0
info:
  title: BigCommerce Pages V3 Pages (Single) API
  version: ''
  termsOfService: http://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  description: "## Overview\n\nA **page** appears on a **site** that is associated with a **channel**. \n\nSome pages, such as blog pages, contact forms, and plain-text or HTML pages, are web pages in the traditional sense. They contain markup (a `body`) and load at a relative page location on the site itself (the `url`). Other pages, such as link and feed pages, make external or non-visual content available from the menu of a parent page or by direct link.\n\n### Bulk operations\nAll endpoints without a `pageId` path parameter support bulk operations.\n\n### Page types\n\nThe following table describes the types of pages that the Pages API can manage:\n\n| Page Type | Description | Body |\n|:-|:|:--|\n| `page` | A user-defined plain-text page. | text |\n| `contact_form` | A user-customizable page that contains a contact form. | HTML |\n| `raw` | A user-defined page that contains HTML markup or other stringified code. | HTML, other code |\n| `blog` | A page that contains blog posts. Use caution; `blog`-type pages can only be created in the store control panel, but you may be able to change the type of a blog page to something else with this API. Use the [Store Content API](/docs/rest-content/store-content/blog-posts#create-a-blog-post) to work with blog posts and tags. | empty string |\n| `feed` | Makes RSS-syndicated content feeds available in the menu of other pages that contain markup. | — |\n| `link` | A link to an external absolute URL. Displays in the menu of other pages that contain markup. | — |"
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Pages (Single)
paths:
  /content/pages/{pageId}:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/pageIdPath'
    get:
      operationId: getPage
      tags:
      - Pages (Single)
      description: 'Returns one content page.


        > #### Warning

        > **Pay attention to query parameters**

        > This endpoint recognizes the same query parameters as [Get Multiple Pages](/docs/rest-content/pages#get-pages). If the requested page does not meet the query parameters you specify, you will receive a 404 response even if the requested `pageId` does exist.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
              examples:
                several data types:
                  value:
                    data:
                    - id: 3
                      channel_id: 1
                      name: Blog
                      meta_title: Blog
                      is_visible: false
                      parent_id: 0
                      sort_order: 4
                      meta_keywords: ''
                      type: blog
                      meta_description: ''
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: '0'
                      url: /blog/
                    - id: 5
                      channel_id: 1
                      name: Contact Us
                      meta_title: ''
                      email: ''
                      is_visible: true
                      parent_id: 0
                      sort_order: 3
                      meta_keywords: contact keyword
                      contact_fields: fullname,companyname,phone,orderno,rma
                      type: contact_form
                      meta_description: contact meta desc
                      is_homepage: false
                      is_customers_only: true
                      search_keywords: contact search keyword
                    - id: 16
                      channel_id: 1
                      name: all about powder detergents 2
                      meta_title: ''
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      meta_keywords: null
                      type: page
                      meta_description: ''
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                    - id: 17
                      channel_id: 1
                      name: one hundred million red balloons 3
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      type: raw
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                      content_type: text/html
                    - id: 18
                      channel_id: 1
                      name: diaper pin purveyors 3
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      link: https://example.com/diaper-pins
                      type: link
                      is_homepage: false
                      is_customers_only: false
                    - id: 19
                      channel_id: 1
                      name: sign up to crush dreams 3
                      meta_title: ''
                      email: ''
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      meta_keywords: null
                      contact_fields: ''
                      type: contact_form
                      meta_description: ''
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                    - id: 20
                      channel_id: 1
                      name: all about powder detergents 3
                      meta_title: ''
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      meta_keywords: null
                      type: page
                      meta_description: ''
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                    - id: 21
                      channel_id: 1
                      name: feed monsters 3
                      meta_title: ''
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      meta_keywords: null
                      feed: /rss/monsters
                      type: feed
                      meta_description: ''
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                    - id: 22
                      channel_id: 1
                      name: one hundred million red balloons 4
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      type: raw
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                      content_type: text/html
                    - id: 23
                      channel_id: 1
                      name: diaper pin purveyors 4
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      link: https://example.com/diaper-pins
                      type: link
                      is_homepage: false
                      is_customers_only: false
                    meta:
                      pagination:
                        total: 6
                        count: 6
                        per_page: 50
                        current_page: 1
                        total_pages: 1
                        links:
                          current: ?page=1&limit=50
        '404':
          description: Not Found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorBrief'
              examples:
                pageId does not exist:
                  value:
                    status: 404
                    title: A Page was not found with an ID of 99
                    type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
        '422':
          description: Invalid input. One or more path parameter(s) did not have the correct datatype.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorItemized'
              examples:
                pageId is bar:
                  value:
                    status: 422
                    title: Invalid Input.
                    type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
                    errors:
                    - bar
      parameters:
      - $ref: '#/components/parameters/includeQuery'
      summary: BigCommerce Get a Page
    put:
      operationId: updatePage
      tags:
      - Pages (Single)
      description: Updates one content page.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PagePut'
        description: ''
        required: true
      responses:
        '200':
          description: '

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
        '400':
          description: Bad Request; reasons for failure include invalid query parameters. See the response for more details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorDetailed'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorBrief'
              examples:
                not found:
                  value:
                    status: 404
                    title: A Page was not found with an ID of 99
                    type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
        '422':
          description: The input was not valid. This error is the result of missing required fields or other invalid arguments. See the response for more details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorDetailed'
      parameters:
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/includeQuery'
      summary: BigCommerce Update a Page
    delete:
      operationId: deletePage
      tags:
      - Pages (Single)
      description: 'Deletes one content page.


        > #### Warning

        > **Query parameters not recognized**

        > This endpoint does not recognize query parameters.'
      responses:
        '204':
          $ref: '#/components/responses/HTTP204'
        '404':
          description: The page specified for deletion did not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorBrief'
              examples:
                example-1:
                  value:
                    status: 404
                    title: A Page was not found with an ID of 99
                    type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
      parameters: []
      summary: BigCommerce Delete a Page
components:
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
    includeQuery:
      schema:
        type: string
        enum:
        - body
      in: query
      name: include
      description: Include the requested property in the response. The `body` property returns the page’s markup, text, or raw content.
    pageIdPath:
      schema:
        type: string
      name: pageId
      in: path
      required: true
      description: The ID of the page to be operated on.
  schemas:
    ResponseErrorItemized:
      type: object
      description: 'Error payload for the BigCommerce API.

        '
      title: ResponseErrorItemized
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          type: string
        errors:
          type: array
          items:
            type: string
      required:
      - status
    Page:
      allOf:
      - type: object
        properties:
          email:
            type: string
            description: 'Applicable when the page type is `contact_form`: contact email address that receives messages sent via the form. Must be unique.'
            maxLength: 255
            default: ''
          meta_title:
            type:
            - string
            - 'null'
          body:
            type:
            - string
            - 'null'
            description: 'HTML or variable that populates this page’s element, in default/desktop view. Required in a `POST` request if the page type is `raw`.

              '
            example: <div>Hello World!</div>
          feed:
            type: string
            description: 'The URL of the RSS feed. Required in a `POST` request if the page type is `rss_feed`.

              '
          link:
            type: string
            description: 'Required in a `POST` request to create a link if the page type is `link`.

              '
          contact_fields:
            type: string
            description: 'Applicable when the page type is `contact_form`: comma-separated list of keywords representing the fields enabled in the control panel for storefront display. Possible fields include:


              |Field|Description|

              |-|-|

              |`fullname`|Full name of the customer submitting the form|

              |`phone`|Customer’s phone number, as submitted on the form|

              |`companyname`|Customer’s submitted company name|

              |`orderno`|Customer’s submitted order number|

              |`rma`|Customer’s submitted RMA (Return Merchandise Authorization) number|

              '
            example: fullname,orderno,rma
            default: ''
          meta_keywords:
            description: 'Comma-separated list of SEO-relevant keywords to include in the page’s element.

              '
            default: ''
            type:
            - string
            - 'null'
          meta_description:
            type:
            - string
            - 'null'
            description: 'Description contained within this page’s element.

              '
          search_keywords:
            type:
            - string
            - 'null'
            description: 'Comma-separated list of keywords that shoppers can use to locate this page when searching the store.

              '
            example: trousers,pockets,luxury
          url:
            type: string
            description: 'Relative URL on the storefront for this page.

              '
            example: /my-store-page
          channel_id:
            type: integer
            description: 'The Id of the channel where this page should be shown.

              '
            example: 12
            default: 1
      - $ref: '#/components/schemas/PageBase'
      title: ''
      description: ''
    PageResponse:
      description: 'Response payload for the BigCommerce API.

        '
      x-examples: {}
      allOf:
      - properties:
          data:
            type: object
            items:
              $ref: '#/components/schemas/Page'
          meta:
            $ref: '#/components/schemas/ResponseMeta'
      title: PageResponseObject
      type: object
    ResponseErrorDetailed:
      type: object
      description: 'Error payload for the BigCommerce API.

        '
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          type: string
        detail:
          type: string
      required:
      - status
    ResponseMeta:
      type: object
      description: 'Data about the response, including pagination and collection totals.

        '
      properties:
        pagination:
          type: object
          description: 'Data about the response, including pagination and collection totals.

            '
          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:
              type: object
              description: 'Pagination links for the previous and next parts of the whole collection.

                '
              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.

                    '
    PagePut:
      type: object
      description: Properties of the page modification request body.
      properties:
        name:
          type: string
          description: 'The name of the page. Must be unique.

            '
          minLength: 1
          maxLength: 100
          example: My Store Page
        is_visible:
          type: boolean
          description: 'Boolean value that specifies the visibility of the page in the storefront’s navigation menu.

            '
        parent_id:
          type: integer
          description: 'ID of any parent Web page.

            '
          example: 0
          default: 0
        sort_order:
          type: integer
          description: 'Specifies the order in which the page is displayed on the storefront. (Lower integers specify earlier display.)

            '
          example: 0
          default: 0
        type:
          type: string
          description: 'Specifies the type of the page.


            |Value|Description|

            |-|-|

            | `blog` | blog page. Read-only; blog pages can only be created in the store control panel. |

            |`contact_form`|hosts the store''s contact form|

            |`link`|link to another absolute URL|

            |`page`|user-defined plain-text page|

            |`raw`|page that contains markup, such as HTML.|

            |`rss_feed`|contains syndicated content from an RSS feed|'
          example: page
          enum:
          - page
          - raw
          - contact_form
          - feed
          - link
          - blog
        is_homepage:
          type: boolean
          description: 'Boolean value that specifies whether this page is the storefront’s home page.

            '
        is_customers_only:
          type: boolean
          description: 'Boolean value. If this value is set to `true`, this page will not be visible when the user is logged in to the store control panel.

            '
        email:
          type: string
          description: 'Applicable when the page type is `contact_form`: contact email address that receives messages sent via the form. Must be unique.'
          maxLength: 255
        meta_title:
          type:
          - string
          - 'null'
        body:
          type:
          - string
          - 'null'
          description: 'HTML or variable that populates the elment of this page, in default/desktop view. Required in a `POST` request if the page type is `raw`.

            '
          example: <div>Hello World!</div>
        feed:
          type: string
          description: 'The URL of the RSS feed. Required in a `POST` request if the page type is `rss_feed`.

            '
        link:
          type: string
          description: 'Required in a `POST` request to create a link if the page type is `link`.

            '
        contact_fields:
          type: string
          description: 'Applicable when the page type is `contact_form`: comma-separated list of keywords representing the fields enabled in the control panel for storefront display. Possible fields include:


            |Field|Description|

            |-|-|

            |`fullname`|Full name of the customer submitting the form|

            |`phone`|Customer’s phone number, as submitted on the form|

            |`companyname`|Customer’s submitted company name|

            |`orderno`|Customer’s submitted order number|

            |`rma`|Customer’s submitted RMA (Return Merchandise Authorization) number|

            '
          example: fullname,companyname,phone,orderno,rma
        meta_keywords:
          default: ''
          type:
          - string
          - 'null'
          description: 'Comma-separated list of SEO-relevant keywords to include in the element of this page.

            '
        meta_description:
          type:
          - string
          - 'null'
          description: 'Description contained within the element of this page.

            '
        search_keywords:
          type:
          - string
          - 'null'
          description: 'Comma-separated list of keywords that shoppers can use to locate this page when searching the store.

            '
          example: trousers,pockets,luxury
        url:
          type: string
          description: 'Relative URL on the storefront for this page.

            '
          example: /my-store-page
        channel_id:
          type: integer
          description: 'The ID of the channel where this page should be shown.

            '
          example: 12
          default: 0
      required:
      - id
    PageBase:
      type: object
      description: Common Page properties.
      properties:
        name:
          type: string
          description: 'The name of the page. Must be unique.

            '
          minLength: 1
          maxLength: 100
          example: My Store Page
        is_visible:
          type: boolean
          description: "Determines the visibility of the page in the storefront’s navigation menu.\n\nBoolean value that specifies the visibility of the page in the storefront’s navigation menu.\n          \nIndicates whether the page is available to users and visible in any menus.\n"
        parent_id:
          type: integer
          description: 'ID of any parent Web page.

            '
          example: 0
          default: 0
        sort_order:
          type: integer
          description: 'Determines the order in which the page is displayed on the storefront. (Lower integers specify earlier display.)

            '
          example: 0
          default: 0
        type:
          type: string
          description: 'Determines the type of the page.


            |Value|Description|

            |-|-|

            | `blog` | blog page. Read-only; blog pages can only be created in the store control panel. |

            |`contact_form`|hosts the store''s contact form|

            |`link`|link to another absolute URL|

            |`page`|user-defined plain-text page|

            |`raw`|page that contains markup, such as HTML.|

            |`rss_feed`|contains syndicated content from an RSS feed|'
          example: page
          enum:
          - page
          - raw
          - contact_form
          - feed
          - link
          - blog
        is_homepage:
          type: boolean
          description: 'Determines whether this page is the storefront’s home page.

            '
        is_customers_only:
          type: boolean
          description: 'If `true`, this page will only be visible to customers that are logged in to the store.

            '
      required:
      - name
      - type
    ResponseErrorBrief:
      type: object
      description: 'Error payload for the BigCommerce API.

        '
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          type: string
      required:
      - status
  responses:
    HTTP204:
      description: No content. A 204 response with no payload indicates successful deletion of all specified pages.
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      name: X-Auth-Token
      in: header
      description: "## API account\n\nYou can use this API with a [store API account or an app API account](https://developer.bigcommerce.com/api-docs/getting-started/rest-api-authentication). \n\n## OAuth scopes \n\n| UI Name | Permission | Parameter | \n|:--|:--|:-| \n| Content | modify     |`store_v2_content`| \n| Content | read-only  |`store_v2_content_read_only`| \n\nFor a [full list of OAuth scopes](https://developer.bigcommerce.com/api-docs/getting-started/rest-api-authentication#oauth-scopes), see our narrative documentation.\n\n## Security header        \n\nInclude a header parameter called `X-Auth-Token` and pass it the `access_token` provided with your store API account or generated with your app's `/auth` callback.\n\n```http filename=\"Security header example\"\n  X-Auth-Token: example_access_token\n```\n\n## Example requests\n\nFor detailed examples, consult our [X-Auth-Token example requests](https://developer.bigcommerce.com/api-docs/getting-started/authentication#x-auth-token-header-example-requests).\n\n## Additional information\n\n[BigCommerce Terms of Service](http://www.bigcommerce.com/terms)"