sitecore Pages API

openapi: 3.2.0
info:
  title: Sitecore XM Cloud REST Pages API
  description: 'The Sitecore XM Cloud REST API provides endpoints for creating and managing collections, sites, pages, languages, and publishing jobs within an XM Cloud tenant. It covers the full lifecycle of site and collection management through the XM Apps system, exposes page authoring operations, and enables programmatic control of publishing workflows. The API follows RESTful conventions and is authenticated via OAuth 2.0 tokens obtained from the Sitecore Cloud Portal automation client credentials. It is organized into several functional areas: the Sites API for managing sites, site collections, and languages; the Pages API for managing site pages; and the Publishing API for creating, monitoring, and managing publishing jobs.'
  version: v1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://xmapps-api.sitecorecloud.io
  description: XM Apps Production Server
- url: https://edge-platform.sitecorecloud.io
  description: Experience Edge Platform Server
security:
- bearerAuth: []
tags:
- name: Pages
  description: Endpoints for managing site pages including full CRUD operations, versioning, variant management, layout editing, field value updates, and publishing state verification.
paths:
  /api/v1/pages:
    get:
      operationId: listPages
      summary: List pages
      description: Retrieves a list of pages for the specified site and environment. Supports filtering by language, version, and other attributes. Results are paginated and include basic page metadata.
      tags:
      - Pages
      parameters:
      - $ref: '#/components/parameters/environmentId'
      - $ref: '#/components/parameters/siteQueryParam'
      - $ref: '#/components/parameters/language'
      responses:
        '200':
          description: A list of pages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Page'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPage
      summary: Create a page
      description: Creates a new page within a site. Pages can be created from blueprints or as blank pages. The request must specify the parent item, page name, template, and optionally an insert options configuration.
      tags:
      - Pages
      parameters:
      - $ref: '#/components/parameters/environmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePageRequest'
      responses:
        '201':
          description: Page created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/pages/{pageId}:
    get:
      operationId: getPage
      summary: Get a page
      description: Retrieves a specific page by its identifier. Returns full page metadata including layout information, version history, field values, and publishing state for the specified language and version.
      tags:
      - Pages
      parameters:
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/environmentId'
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/version'
      responses:
        '200':
          description: Page details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePage
      summary: Delete a page
      description: Permanently deletes a page and all its versions and language variants. This operation is irreversible. Child pages are also deleted unless they are moved prior to deletion.
      tags:
      - Pages
      parameters:
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/environmentId'
      responses:
        '204':
          description: Page deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    environmentId:
      name: sc_env
      in: query
      description: The XM Cloud environment identifier
      required: false
      schema:
        type: string
    siteQueryParam:
      name: siteId
      in: query
      description: Filter results by site identifier
      required: false
      schema:
        type: string
    version:
      name: version
      in: query
      description: Content version number to retrieve
      required: false
      schema:
        type: integer
    language:
      name: language
      in: query
      description: Language code for the content (e.g., en, fr-FR)
      required: false
      schema:
        type: string
    pageId:
      name: pageId
      in: path
      description: The unique identifier of the page item
      required: true
      schema:
        type: string
  schemas:
    CreatePageRequest:
      type: object
      description: Request body for creating a new page
      required:
      - name
      - parentId
      - templateId
      - siteId
      - language
      properties:
        name:
          type: string
          description: The item name for the new page
        displayName:
          type: string
          description: The display name for the new page
        parentId:
          type: string
          description: The identifier of the parent item under which the page is created
        templateId:
          type: string
          description: The identifier of the template to use for the page
        siteId:
          type: string
          description: The identifier of the site to create the page in
        language:
          type: string
          description: The language of the initial page version
    Page:
      type: object
      description: A page item within an XM Cloud site
      properties:
        id:
          type: string
          description: The unique Sitecore item identifier for the page
        name:
          type: string
          description: The item name of the page
        displayName:
          type: string
          description: The display name of the page shown in navigation
        path:
          type: string
          description: The Sitecore item path of the page
        language:
          type: string
          description: The language of the page content
        version:
          type: integer
          description: The version number of the page content
        templateId:
          type: string
          description: The identifier of the template used by this page
        publishingState:
          type: string
          description: The current publishing state of the page
          enum:
          - Draft
          - Published
          - NeedsPublishing
        url:
          type: string
          description: The relative URL of the page within the site
          format: uri
    ProblemDetails:
      type: object
      description: RFC 7807 problem details response for errors
      properties:
        type:
          type: string
          description: A URI reference identifying the problem type
        title:
          type: string
          description: A short human-readable summary of the problem
        status:
          type: integer
          description: The HTTP status code for this occurrence of the problem
        detail:
          type: string
          description: A human-readable explanation of the problem
        instance:
          type: string
          description: A URI reference identifying the specific occurrence of the problem
  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained via OAuth 2.0 client credentials flow. Request tokens from https://auth.sitecorecloud.io/oauth/token using automation client credentials created in the Sitecore Cloud Portal. Tokens expire after 24 hours.
externalDocs:
  description: Sitecore XM Cloud Developer Documentation
  url: https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-xm-cloud.html