# Create a publishing job

Creates a new publishing job. To create a publishing job, your token must include one of the following scopes ` xmcpub.jobs.a:w`, `xmcpub.jobs.t:w`, or `xmcpub.jobs.t:wl`. Users with a scope of `xmcpub.jobs.t:wl`  (limited write) must also have `Sitecore Client Advanced Publishing` or `Sitecore Client Publishing`  roles or have the `admin` flag set in XM Cloud.    Client token of applications must have the `xmcloud.cm:admin` scope.

Endpoint: POST /authoring/publishing/v1/jobs
Version: v1.0
Security: Bearer

## Security:

  - `Bearer` (unknown)
    http bearer JWT

## Request body:

  - `application/json, text/json, application/*+json` (unknown)
    The request for creating the job.

## Request fields (application/json):

  - `name` (string, required)
    Name of the job.

  - `source` (string, required)
    Source of the job. This is typically the application name specified as the source (for example, `Pages`, `Sites`, and so on).

  - `options` (object, required)
    The publish job options.

  - `options.items` (array)
    Root items to start publishing from.

  - `options.items.id` (string, required)
    ID of the item to publish.

  - `options.items.type` (string, required)
    Type of the item to publish (for example, `Page`, `Site`, `Item`, and so on).

  - `options.items.locale` (string)
    Locale of the item to publish. Items can have a locale
equal to `*`, which means that items must be published in all
languages. `locale` must be specified for each item or as a list
in `options.xmc.locales`.

**Note**
A combination of locale in item and in `options.xmc.locales` is not allowed.

Valid format is `xx` or `xx-YY`, where `xx` is ISO-639-1 language
code and `YY` is ISO 3166-1 country code.

  - `options.xmc` (object)
    Represents a model for XMC publishing.

  - `options.xmc.locales` (array)
    Locales in which content is to be published. This field is required
for XM Cloud site publishing jobs (when `options.xmc.site` is set)
and is optional for XM Cloud items publishing jobs.

**Note**
When it is specified for items publishing none of the items should have `locale` set.

The format of each element in array must be `xx` or `xx-YY`,
where `xx` is ISO-639-1 language code and `YY` is ISO 3166-1 country code.

  - `options.xmc.site` (object)
    Site options for publishing.

  - `options.xmc.site.mode` (string, required)
    Mode of the items publish job.
    Enum: "Republish", "Incremental", "Smart"

  - `options.xmc.items` (object)
    Represents the items options for publishing.

  - `options.xmc.items.publishRelatedItems` (boolean)
    Whether to publish related items.

  - `options.xmc.items.publishChildren` (boolean)
    Whether to publish children items recursively.

  - `options.xmc.items.mode` (string, required)
    Mode of the items publish job.
    Enum: "Republish", "Smart"

  - `description` (string)
    Description of the job.

## Response 201:

  - `201` (unknown)
    Job successfully created.

## Response 201 fields (application/json):

  - `id` (string, required)
    The ID of the job.

  - `description` (string)
    The description of the job.

  - `name` (string, required)
    The name of the job.

  - `options` (object, required)
    The options the publishing job was created with.

  - `options.xmc` (object)
    XMC publishing options.

  - `options.xmc.locales` (array, required)
    Locales in which content is to be published.

  - `source` (string, required)
    The source of the job.

  - `statistics` (object)
    The job statistics.

  - `statistics.lastReportTime` (string)
    The last time the statistics were updated.

  - `statistics.itemsSent` (integer)
    The number of items sent.

  - `statistics.itemsProcessed` (integer)
    The number of items processed.

  - `statistics.itemsFailed` (integer)
    The number of items failed.

  - `statistics.xmc` (object)
    Additional fields of the XMC statistics.

  - `statistics.xmc.additionalItemsSent` (integer)
    The number of additional items sent.

  - `statistics.xmc.itemsAcknowledged` (integer)
    The number of items acknowledged.

  - `statistics.xmc.itemsDeleted` (integer)
    The number of items deleted.

  - `statistics.xmc.itemsSkipped` (integer)
    The number of items skipped.

  - `statistics.xmc.itemsSendingComplete` (boolean)
    Indicates whether the sending of items is complete.

  - `system` (object)
    The system data of a job.

  - `system.organizationId` (string, required)
    The ID of the organization that the job belongs to.

  - `system.tenantId` (string, required)
    The ID of the tenant that the job belongs to.

  - `system.tenantJobId` (string)
    The job ID on the tenant side.

  - `system.status` (string, required)
    The status of the job.
    Enum: "Queued", "Running", "Completed", "Failed", "Canceled", "Canceling"

  - `system.queuedTime` (string)
    The time when the job was queued.

  - `system.startTime` (string)
    The time when the job was started.

  - `system.finishTime` (string)
    The time when the job was finished.

  - `system.createdBy` (object)
    The service client description.

  - `system.createdBy.id` (string, required)
    The ID of service client.

  - `system.createdBy.name` (string, required)
    The name of service client.

  - `system.createdBy.type` (string, required)
    The type of service client.
    Enum: "Application", "User"

  - `permissions` (object, required)
    The permissions of the current user or application to work with the job.

  - `permissions.canViewDetails` (boolean)
    Whether details of the publishing job can be viewed.

  - `permissions.canCancel` (boolean)
    Whether the publishing job can be canceled.

## Response 400:

  - `400` (unknown)
    Bad Request. Possible reasons:  - Invalid name  - Invalid description  - Invalid items  - Invalid mode  - Invalid locales - Invalid source  - Invalid tenant

## Response 400 fields (application/json):

  - `type` (string)

  - `title` (string)

  - `status` (integer)

  - `detail` (string)

  - `instance` (string)

## Response 401:

  - `401` (unknown)
    Unauthorized request or invalid access token

## Response 401 fields (application/json):

  - `type` (string)

  - `title` (string)

  - `status` (integer)

  - `detail` (string)

  - `instance` (string)

## Response 403:

  - `403` (unknown)
    Request does not contain required scopes

## Response 403 fields (application/json):

  - `type` (string)

  - `title` (string)

  - `status` (integer)

  - `detail` (string)

  - `instance` (string)