openapi: 3.0.1
info:
  title: Jobs API
  description: >
    Use the Jobs API to retrieve, create, update, and delete job targets or the
    description.

    This REST API lets you interact with:
      
       - <i>M.Target</i> entities, which are targets of a job.
       - The <i>M.JobDescription</i> entity, which contains information about what to do and what is in progress.

    {% admonition type="info" name="Note" %} To help you switch to the Jobs API,
    we provide [guidance on how to update calls in your
    code](https://doc.sitecore.com/ch/en/developers/cloud-dev/switch-to-the-jobs-api.html).
    {% /admonition %}

     ## Authentication

     To use the <b>Try it</b> feature of the Jobs API, you need:

      - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the <b>{{server}}</b> variable by hovering over the variable in the <b>Try it</b> pane and then clicking <b>Edit</b>.
      - An [access token and the client ID](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests). Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html)  or by [requesting one to the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows)
  version: v2.0
  x-metadata:
    product: Content Hub
  license:
    name: closed source
    url: https://www.sitecore.com
servers:
  - url: https://{server}
    variables:
      server:
        default: your-server
security:
  - oauth2: []
tags:
  - name: Jobs
    description: 'The Jobs endpoint is used to retrieve a specific job.  '
  - name: Job description
    description: >-
      The Job description entity contains information for the worker about what
      needs to be done and what is in progress.
  - name: Targets
    description: >-
      A target entity is a target of a job (meaning a background process). Each
      job can have one or more targets.
paths:
  /api/v2/jobs/{id}:
    get:
      tags:
        - Jobs
      summary: Retrieve a job
      description: >-
        Retrieves a job with a specified ID. Job targets are not retrieved. Only
        the link to the relation is used. You can get the job ID in the [Job
        details](https://doc.sitecore.com/ch/en/users/content-hub/job-details.html)
        or in the URL when you click a job target on the <b>Processing</b> page
        (for example,
        `https://contenthub-server.cloud/en-us/user/myjobs/Job/39309` ).
      operationId: JobByIdV2
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example, `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: cultures
          in: query
          description: >-
            List of cultures in which to load the entity. If no cultures are
            provided, multi-language properties are not included.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResource'
        '400':
          description: >-
            Request or Job ID not valid (for example, less than or equal to zero
            or does not exist), or at least one culture is null.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
  /api/jobs/{id}/targets:
    post:
      tags:
        - Targets
      summary: Create a job target
      description: >-
        Creates a new target for the specified job and returns the job target
        ID, for example `39605`.
      operationId: CreateTarget
      parameters:
        - name: id
          in: path
          description: The ID for the job target, for example `39605`.
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The request containing the target information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityPostResource'
        required: true
      responses:
        '201':
          description: Target successfully created.
        '400':
          description: >-
            Request not valid (for example, less than or equal to zero), or
            target resource is null.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
    get:
      tags:
        - Targets
      summary: Retrieve all job targets
      description: Lists all the targets associated with a job that match the criteria.
      operationId: JobTargets
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example, `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: state
          in: query
          description: The state of the job targets.
          schema:
            type: string
          example: Completed
        - name: condition
          in: query
          description: The condition of the job targets.
          schema:
            type: string
          example: Pending
        - name: type
          in: query
          description: The type of the job targets.
          schema:
            type: string
          example: Import
        - name: location
          in: query
          description: The location of the targets. This is a full string match.
          schema:
            type: string
        - name: skip
          in: query
          description: The number of items to skip.
          schema:
            type: integer
            format: int32
            default: 0
        - name: take
          in: query
          description: The number of items to take.
          schema:
            type: integer
            format: int32
            default: 25
        - name: cultures
          in: query
          description: >-
            List of cultures in which to load the entity. If no cultures are
            provided, multi-language properties are not included.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCollectionResource'
        '400':
          description: >-
            Request or Job ID not valid (for example, less than or equal to zero
            or does not exist), or at least one culture is null.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
  /api/jobs/{id}/description:
    get:
      tags:
        - Job description
      summary: Retrieve the job description
      description: >-
        Retrieves the description for a specific job using its ID, for example
        `39595`.
      operationId: JobDescription
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: cultures
          in: query
          description: >-
            List of cultures in which to load the entity. If no cultures are
            provided, multi-language properties are not included.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResource'
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
    put:
      tags:
        - Job description
      summary: Create or update the job description
      description: >-
        Creates a job description entity if it does not exist or updates the job
        description entity. It confirms that the job exists and that the user
        has permission to access it. Properties or relations not included in the
        request will be set to null.
      operationId: CreateOrUpdateDescription
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The request containing the job description information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobDescriptionResource'
        required: true
      responses:
        '201':
          description: Job description successfully created.
        '204':
          description: Job description successfully updated.
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
    patch:
      tags:
        - Job description
      summary: Partially update the job description
      description: >-
        Updates part of the job description entity. It confirms that both the
        job and description exist and that the user has permission to modify
        them. Properties or relations not included in the request will be set to
        null.
      operationId: PartialUpdateDescription
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The request containing the updated job description information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityResource'
        required: true
      responses:
        '204':
          description: Entity successfully updated.
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
    delete:
      tags:
        - Job description
      summary: Delete the job description
      description: >-
        Deletes the description associated with a job. It confirms that both the
        job and description exist and that the user has permission to access
        them.
      operationId: DeleteDescription
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: Successful deletion.
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
  /api/jobs/{id}/description/{descriptionId}:
    get:
      tags:
        - Job description
      summary: Retrieve the job description
      description: >-
        Retrieves the description for a specific job using its ID, for example
        `39595`.
      operationId: JobDescriptionById
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: descriptionId
          in: path
          description: The ID for the job description, for example `98765`.
          required: true
          schema:
            type: integer
            format: int64
        - name: cultures
          in: query
          description: >-
            List of cultures in which to load the entity. If no cultures are
            provided, multi-language properties are not included.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResource'
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
  /api/jobs/{id}/targets/bulk:
    post:
      tags:
        - Targets
      summary: Create multiple job targets at once
      description: >-
        Creates new targets for the specified job and returns the job target
        IDs.
      operationId: CreateTargets
      parameters:
        - name: id
          in: path
          description: The ID for the job target, for example `39605`.
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The request containing target information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityPostCollectionResource'
        required: true
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCreatedCollectionResource'
        '201':
          description: Targets successfully created.
        '400':
          description: >-
            Request not valid (for example, less than or equal to zero), or
            target resources are null.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
  /api/jobs/{id}/targets/{targetId}:
    get:
      tags:
        - Targets
      summary: Retrieve a specific job target
      description: Retrieves a job target using the job ID and the target ID.
      operationId: JobTarget
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: targetId
          in: path
          description: The target ID, for example `34489`.
          required: true
          schema:
            type: integer
            format: int64
        - name: cultures
          in: query
          description: >-
            List of cultures in which to load the entity. If no cultures are
            provided, multi-language properties are not included.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResource'
        '400':
          description: >-
            Request or Job ID not valid (for example, less than or equal to zero
            or does not exist), or at least one culture is null.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
    put:
      tags:
        - Targets
      summary: Update a job target
      description: >-
        Updates a target associated with a job. It ensures that both the job and
        target exist and that the user has access to them. Properties or
        relations not included in the request will be set to null.
      operationId: UpdateTarget
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: targetId
          in: path
          description: The target ID, for example `39595`.
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The request containing the updated target information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityResource'
        required: true
      responses:
        '204':
          description: Successful operation.
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
    patch:
      tags:
        - Targets
      summary: Partially update a job target
      description: >-
        Partial update on a target associated with a job. It ensures that the
        job and target exist and that the user has access to them. The
        properties and relations included in the request will be updated.
      operationId: PartialUpdateTarget
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: targetId
          in: path
          description: The target ID, for example `39595`.
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The request containing the updated target information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityResource'
        required: true
      responses:
        '204':
          description: Successful operation.
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
    delete:
      tags:
        - Targets
      summary: Delete a job target
      description: Deletes a target for a job using its ID.
      operationId: DeleteTarget
      parameters:
        - name: id
          in: path
          description: The ID for the job, for example `39596`.
          required: true
          schema:
            type: integer
            format: int64
        - name: targetId
          in: path
          description: The target ID, for example `39595`.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: Entity successfully deleted.
        '400':
          description: Request not valid or error during operation.
        '401':
          description: Unauthorized request.
        '404':
          description: Entity not found or user not authorized.
      security:
        - oauth2: []
components:
  schemas:
    EntityCollectionResource:
      type: object
      properties:
        last_hit_data:
          type: array
          items:
            type: string
          description: >-
            The last returned hits, which are used to fetch the next page of
            results.
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/EntityResource'
          description: Gets or sets the list of items.
          nullable: true
        total_items:
          type: integer
          description: Gets or sets the total number of items.
          format: int64
          nullable: true
        returned_items:
          type: integer
          description: Gets or sets the number of returned items.
          format: int64
          nullable: true
        offset:
          type: integer
          description: Gets or sets the offset of the items.
          format: int32
          nullable: true
        next:
          $ref: '#/components/schemas/Link'
        previous:
          $ref: '#/components/schemas/Link'
        identifier:
          type: string
          description: Gets or sets the identifier of the resource.
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: {}
      description: Collection of entities that are the result of a query
    EntityCreatedCollectionResource:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EntityCreatedResource'
          description: Gets or sets the list of items.
          nullable: true
        total_items:
          type: integer
          description: Gets or sets the total number of items.
          format: int64
          nullable: true
        returned_items:
          type: integer
          description: Gets or sets the number of returned items.
          format: int64
          nullable: true
        offset:
          type: integer
          description: Gets or sets the offset of the items.
          format: int32
          nullable: true
        next:
          $ref: '#/components/schemas/Link'
        previous:
          $ref: '#/components/schemas/Link'
        identifier:
          type: string
          description: Gets or sets the identifier of the resource.
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: {}
      description: >-
        Represents a collection resource of entities that have been created.
        Inherits from Stylelabs.M.Base.Web.Api.Models.ListResource`1.
    EntityCreatedResource:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the entity.
          format: int64
        identifier:
          type: string
          description: The identifier string for the entity.
          nullable: true
        link:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
      description: Represents a resource for a new created entity.
    EntityLink:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: Gets or sets the nested properties of the entity link.
          nullable: true
        renditions:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: Gets or sets the nested renditions of the entity link.
          nullable: true
        permissions:
          type: array
          items:
            type: string
          description: Gets or sets the nested permissions of the entity link.
          nullable: true
        identifier:
          type: string
          description: Gets or sets the nested identifier of the entity link.
          nullable: true
        href:
          type: string
          description: >-
            Gets or sets the URI that points to the resource this link refers
            to.
          nullable: true
        filename_properties:
          type: array
          items:
            type: string
          description: >-
            Gets or sets the URI that points to the resource this link refers
            to.
          nullable: true
        title:
          type: string
          description: Gets or sets the title that describes this link.
          nullable: true
        templated:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the contained URI is a
            template.
          default: false
      additionalProperties: false
      description: >-
        Represents a link to an entity with additional properties, renditions,
        permissions, and identifier.
    EntityPostCollectionResource:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EntityPostResource'
          description: Gets or sets the list of items.
          nullable: true
      additionalProperties: false
      description: >-
        Represents a collection resource for posting entities. Inherits from
        Stylelabs.M.Base.Web.Api.Models.ListResource`1.
    EntityPostResource:
      type: object
      properties:
        id:
          type: integer
          description: Gets or sets the entity ID.
          format: int64
          nullable: true
        identifier:
          type: string
          description: Gets or sets the entity identifier.
          nullable: true
        properties:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: Gets or sets the properties of the entity.
          nullable: true
        relations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RelationResource'
          description: Gets or sets the relations of the entity.
          nullable: true
        is_root_taxonomy_item:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the entity is a root
            taxonomy item.
          nullable: true
        is_path_root:
          type: boolean
          description: Gets or sets a value indicating whether the entity is a path root.
          nullable: true
        entitydefinition:
          $ref: '#/components/schemas/Link'
        is_system_owned:
          type: boolean
          description: Gets or sets a value indicating whether the entity is system owned.
        inherits_security:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the entity inherits
            security.
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
      description: Represents a resource for creating an entity.
    EntityResource:
      type: object
      properties:
        id:
          type: integer
          description: The ID for the entity, for example `39752`.
          format: int64
        identifier:
          type: string
          description: The identifier for the entity.
          nullable: true
        cultures:
          type: array
          items:
            type: string
          description: The cultures associated with the entity, for example `en-US`.
          nullable: true
        properties:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: The properties of the entity.
          nullable: true
        relations:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: The relations of the entity.
          nullable: true
        created_by:
          $ref: '#/components/schemas/Link'
        created_on:
          type: string
          description: The date and time when the entity was created.
          format: date-time
        modified_by:
          $ref: '#/components/schemas/Link'
        modified_on:
          type: string
          description: The date and time when the entity was last modified.
          format: date-time
        locked_by:
          $ref: '#/components/schemas/Link'
        locked_on:
          type: string
          description: The date and time when the entity was locked.
          format: date-time
          nullable: true
        entitydefinition:
          $ref: '#/components/schemas/Link'
        copy:
          $ref: '#/components/schemas/Link'
        copyasync:
          $ref: '#/components/schemas/Link'
        permissions:
          $ref: '#/components/schemas/Link'
        requested_permissions:
          type: object
          additionalProperties:
            type: boolean
            nullable: true
          description: >-
            The requested permissions with identification if a certain user has
            permission.
          nullable: true
        lifecycle:
          $ref: '#/components/schemas/Link'
        saved_selections:
          $ref: '#/components/schemas/Link'
        roles:
          $ref: '#/components/schemas/Link'
        annotations:
          $ref: '#/components/schemas/Link'
        is_root_taxonomy_item:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the entity is a root
            taxonomy item.
          nullable: true
        is_path_root:
          type: boolean
          description: Gets or sets a value indicating whether the entity is a path root.
          nullable: true
        inherits_security:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the entity inherits
            security.
        is_system_owned:
          type: boolean
          description: Gets or sets a value indicating whether the entity is system owned.
        version:
          type: integer
          description: The version of the entity.
          format: int64
        full:
          $ref: '#/components/schemas/Link'
        modules:
          type: array
          items:
            type: string
          description: The modules associated with the entity.
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: {}
      description: >-
        Represents an entity resource with various properties, relations and
        metadata.
    JobDescriptionResource:
      type: object
      properties:
        id:
          type: integer
          description: The unique job description ID.
          format: int64
          nullable: true
        identifier:
          type: string
          description: The unique job description identifier.
          nullable: true
        properties:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: The job description properties.
          nullable: true
        relations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RelationResource'
          description: The job description relations.
          nullable: true
        is_root_taxonomy_item:
          type: boolean
          description: >-
            A value indicating whether the job description is a root taxonomy
            item.
          nullable: true
        is_path_root:
          type: boolean
          description: A value indicating whether the job description is a path root.
          nullable: true
        entity_definition:
          $ref: '#/components/schemas/Link'
        is_system_owned:
          type: boolean
          description: A value indicating whether the job description is system owned.
        inherits_security:
          type: boolean
          description: A value indicating whether the job description inherits security.
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
      description: >-
        Represents a job description resource with various properties and
        relations.
    Link:
      type: object
      properties:
        href:
          type: string
          description: >-
            Gets or sets the URI that points to the resource this link refers
            to.
          nullable: true
        filename_properties:
          type: array
          items:
            type: string
          description: >-
            Gets or sets the URI that points to the resource this link refers
            to.
          nullable: true
        title:
          type: string
          description: Gets or sets the title that describes this link.
          nullable: true
        templated:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the contained URI is a
            template.
          default: false
      additionalProperties: false
      description: Represents a link to a resource.
    RelationResource:
      type: object
      properties:
        parents:
          type: array
          items:
            $ref: '#/components/schemas/EntityLink'
          description: The relation parents.
          nullable: true
        parent:
          $ref: '#/components/schemas/EntityLink'
        children:
          type: array
          items:
            $ref: '#/components/schemas/EntityLink'
          description: The relation children.
          nullable: true
        child:
          $ref: '#/components/schemas/EntityLink'
        inherits_security:
          type: boolean
          description: A value indicating whether the relation inherits security.
          nullable: true
        parent_total:
          type: integer
          description: >-
            Displays the total number of parents in the resource when the
            relation resource is limited.
          format: int64
          nullable: true
        child_total:
          type: integer
          description: >-
            Displays the total number of children in the resource when the
            relation resource is limited.
          format: int64
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
      description: Represents an relation resource.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
