openapi: 3.1.0
info:
  title: Sitecore CDP REST Audit Publishing Jobs API
  description: The Sitecore CDP REST API provides synchronous access to retrieve, create, update, and delete data stored in Sitecore Customer Data Platform. It exposes guest profiles, orders, order items, order contacts, order consumers, and data extensions through standard HTTP methods. Developers use this API to build integrations that read or write customer data programmatically, enabling use cases such as audience segmentation, data enrichment, and reporting. Authentication uses HTTP Basic Auth with a client key and API token obtained from the CDP instance settings. Regional server endpoints must be used based on the CDP instance's geographic deployment.
  version: v2.1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://api-engage-eu.sitecorecloud.io
  description: EU Production Server
- url: https://api-engage-us.sitecorecloud.io
  description: US Production Server
- url: https://api-engage-ap.sitecorecloud.io
  description: Asia-Pacific Production Server
- url: https://api-engage-jpe.sitecorecloud.io
  description: Japan Production Server
security:
- basicAuth: []
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:
  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'
  schemas:
    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
    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
    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
    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
  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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using a client key as the username and an API token as the password. Credentials are obtained from Sitecore CDP Settings > API access.
externalDocs:
  description: Sitecore CDP REST API Documentation
  url: https://doc.sitecore.com/cdp/en/developers/api/rest-apis.html