sitecore Publishing Jobs API

openapi: 3.2.0
info:
  title: Sitecore XM Cloud REST Publishing Jobs 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: Publishing Jobs
  description: Endpoints for creating, monitoring, and managing publishing jobs that push content from XM Cloud authoring to the Experience Edge delivery layer.
paths:
  /authoring/publishing/v1/jobs:
    get:
      operationId: listPublishingJobs
      summary: List publishing jobs
      description: Retrieves a paginated list of publishing jobs for the authenticated tenant and environment. Jobs can be filtered by status, date range, and other criteria. Returns job metadata including status, creation time, and item processing metrics.
      tags:
      - Publishing Jobs
      parameters:
      - $ref: '#/components/parameters/environmentId'
      - name: status
        in: query
        description: Filter jobs by status
        required: false
        schema:
          $ref: '#/components/schemas/JobStatus'
      - name: pageSize
        in: query
        description: Number of jobs to return per page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: A paginated list of publishing jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishingJobList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPublishingJob
      summary: Create a publishing job
      description: Creates and queues a new publishing job to push content from XM Cloud authoring to the Experience Edge delivery layer. The job can target specific items, languages, or be configured as a full site publish.
      tags:
      - Publishing Jobs
      parameters:
      - $ref: '#/components/parameters/environmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePublishingJobRequest'
      responses:
        '202':
          description: Publishing job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishingJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /authoring/publishing/v1/jobs/{id}:
    get:
      operationId: getPublishingJob
      summary: Get a publishing job
      description: Retrieves a specific publishing job by its identifier. Returns the current status, progress metrics, and any error information for the job.
      tags:
      - Publishing Jobs
      parameters:
      - $ref: '#/components/parameters/jobId'
      - $ref: '#/components/parameters/environmentId'
      responses:
        '200':
          description: Publishing job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishingJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /authoring/publishing/v1/jobs/{jobId}/cancel:
    post:
      operationId: cancelPublishingJob
      summary: Cancel a publishing job
      description: Cancels an active publishing job that is currently queued or running. Jobs in a terminal state (Completed, Failed, Canceled) cannot be cancelled. Returns the updated job with a Canceling or Canceled status.
      tags:
      - Publishing Jobs
      parameters:
      - $ref: '#/components/parameters/jobId'
      - $ref: '#/components/parameters/environmentId'
      responses:
        '200':
          description: Publishing job cancellation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishingJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /authoring/publishing/v1/jobs/summary:
    get:
      operationId: getPublishingJobSummary
      summary: Get publishing job summary
      description: Retrieves statistical summary information about publishing jobs within the tenant, including counts by status, recent activity metrics, and item processing totals.
      tags:
      - Publishing Jobs
      parameters:
      - $ref: '#/components/parameters/environmentId'
      responses:
        '200':
          description: Publishing job statistics summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishingJobSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    PublishingJobSummary:
      type: object
      description: Statistical summary of publishing jobs for the tenant
      properties:
        queued:
          type: integer
          description: Number of jobs currently queued
        running:
          type: integer
          description: Number of jobs currently running
        completed:
          type: integer
          description: Number of jobs completed
        failed:
          type: integer
          description: Number of jobs that failed
        canceled:
          type: integer
          description: Number of jobs that were canceled
    JobStatus:
      type: string
      description: The current status of a publishing job
      enum:
      - Queued
      - Running
      - Completed
      - Failed
      - Canceled
      - Canceling
    PublishingJob:
      type: object
      description: A publishing job that pushes content to Experience Edge
      properties:
        id:
          type: string
          description: The unique identifier of the publishing job
        status:
          $ref: '#/components/schemas/JobStatus'
        createdAt:
          type: string
          description: The ISO 8601 timestamp when the job was created
          format: date-time
        startedAt:
          type: string
          description: The ISO 8601 timestamp when the job started processing
          format: date-time
        completedAt:
          type: string
          description: The ISO 8601 timestamp when the job finished
          format: date-time
        totalItems:
          type: integer
          description: Total number of items to be processed by the job
        processedItems:
          type: integer
          description: Number of items processed so far
        failedItems:
          type: integer
          description: Number of items that failed to publish
    CreatePublishingJobRequest:
      type: object
      description: Request body for creating a new publishing job
      required:
      - targetId
      properties:
        targetId:
          type: string
          description: The identifier of the publishing target (e.g., Experience Edge)
        itemIds:
          type: array
          description: Specific item identifiers to publish; omit for full publish
          items:
            type: string
        languages:
          type: array
          description: Language codes to publish; omit for all languages
          items:
            type: string
        includeSubitems:
          type: boolean
          description: Whether to include child items in the publish
          default: true
    PublishingJobList:
      type: object
      description: A paginated list of publishing jobs
      properties:
        items:
          type: array
          description: The list of publishing jobs for the current page
          items:
            $ref: '#/components/schemas/PublishingJob'
        totalCount:
          type: integer
          description: The total number of jobs matching the query
        pageSize:
          type: integer
          description: The number of items returned per page
    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
  parameters:
    jobId:
      name: jobId
      in: path
      description: The unique identifier of the publishing job
      required: true
      schema:
        type: string
    environmentId:
      name: sc_env
      in: query
      description: The XM Cloud environment identifier
      required: false
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      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'
    NotFound:
      description: The requested resource was not found
      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