openapi: 3.0.1
info:
  title: Download orders API
  description: >
    Use the Download orders API to create and retrieve download orders. A
    download order is a compressed file that contains media files, such as
    images, vectors, or videos.

    ## Authentication

    To use the Download orders 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. 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: v1.0
  x-metadata:
    product: Content Hub
  license:
    name: closed source
    url: https://www.sitecore.com
servers:
  - url: https://{server}
    variables:
      server:
        default: your-server
tags:
  - name: Download orders
    description: >-
      A download order is a compressed file that contains media files along with
      the download order configuration.
paths:
  /api/downloadorders/{id}:
    get:
      tags:
        - Download orders
      summary: Retrieve a download order with a specific ID
      description: >-
        Retrieves a download order with a specific ID along with download
        details, such as the target count, whether the order has conversions,
        who created the order and when, as well as the download status.
      operationId: DownloadOrdersById
      parameters:
        - name: id
          in: path
          description: The identifier of the download order.
          required: true
          schema:
            type: integer
            format: int64
        - name: If-Modified-Since
          in: header
          description: >-
            Optional. The date after which to verify if the download order was
            modified. If the order was modified, a 304 response code is
            returned.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadOrderResource'
        '304':
          description: Download order not modified
        '401':
          description: Unauthorized request
        '404':
          description: Download order not found or user not authorized
      security:
        - oauth2: []
  /api/downloadorders:
    get:
      tags:
        - Download orders
      summary: Retrieve multiple download orders
      description: Lists the download orders that the current user has access to.
      operationId: DownloadOrders
      parameters:
        - name: skip
          in: query
          description: The number of items to skip for pagination.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadOrderCollectionResource'
        '401':
          description: Unauthorized request
        '404':
          description: Download order not found or user not authorized
      security:
        - oauth2: []
    post:
      tags:
        - Download orders
      summary: Create a download order
      description: >-
        Creates a download order for the specified assets using the defined
        download options.
      operationId: AddDownloadOrders
      requestBody:
        description: A download order request that contains the order details.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/DownloadOrderRequestResource'
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadOrderRequestResource'
          text/json:
            schema:
              $ref: '#/components/schemas/DownloadOrderRequestResource'
          application/*+json:
            schema:
              $ref: '#/components/schemas/DownloadOrderRequestResource'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadOrderResource'
        '400':
          description: Request not valid
        '401':
          description: Unauthorized request
      security:
        - oauth2: []
  /api/downloadorders/{orderId}/targets/{entityId}:
    get:
      tags:
        - Download orders
      summary: Retrieve a download order target
      description: Retrieves a download order for the specified order and target ID.
      operationId: DownloadOrderTargetsByEntityId
      parameters:
        - name: orderId
          in: path
          description: The ID of the download order.
          required: true
          schema:
            type: integer
            format: int64
        - name: entityId
          in: path
          description: The ID of the target entity.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadOrderTargetResource'
        '401':
          description: Unauthorized request
        '404':
          description: Download order target not found or user not authorized
      security:
        - oauth2: []
  /api/downloadorders/{orderId}/targets:
    get:
      tags:
        - Download orders
      summary: Retrieve the download order targets
      description: Retrieves the download order targets for the specified order ID.
      operationId: DownloadOrderTargets
      parameters:
        - name: orderId
          in: path
          description: The unique identifier of the order.
          required: true
          schema:
            type: integer
            format: int64
        - name: skip
          in: query
          description: The number of items to skip for pagination.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadOrderTargetCollectionResource'
        '401':
          description: Unauthorized request
        '404':
          description: Download order targets not found or user not authorized
      security:
        - oauth2: []
components:
  schemas:
    ConversionParameterResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ProcessingParameter'
        value:
          $ref: '#/components/schemas/IProcessingParameterValue'
      additionalProperties: false
      description: Represents one processing option.
    DownloadOrderCollectionResource:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DownloadOrderResource'
          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 of download order resources.
    DownloadOrderRequestResource:
      required:
        - order
      type: object
      properties:
        target_selection:
          $ref: '#/components/schemas/SelectionResource'
        item_name_resolver_id:
          type: string
          description: The ID of the item name resolver.
          nullable: true
        culture:
          type: string
          description: The culture code of the download order, for example, `en-US`.
          nullable: true
        name:
          type: string
          description: The name of the download order.
          nullable: true
        order:
          $ref: '#/components/schemas/OrderRequestResource'
        download_order_type:
          $ref: '#/components/schemas/DownloadOrderType'
      additionalProperties: false
    DownloadOrderResource:
      type: object
      properties:
        order_id:
          type: integer
          description: The ID of the download order.
          format: int64
        name:
          type: string
          description: The name of the download order.
          nullable: true
        target_count:
          type: integer
          description: The number of targets contained in the download order.
          format: int64
        has_conversions:
          type: boolean
          description: Whether the order contains converted files or not.
        created_by:
          $ref: '#/components/schemas/Link'
        created_on:
          type: string
          description: The date the download order was created.
          format: date-time
          nullable: true
        modified_by:
          $ref: '#/components/schemas/Link'
        status:
          type: string
          description: The status of the download order, for example, `Completed`.
          nullable: true
        download_location:
          $ref: '#/components/schemas/Link'
        additional_info:
          type: string
          description: Additional information about the download order.
          nullable: true
        external_job_reference:
          $ref: '#/components/schemas/Link'
        targets:
          $ref: '#/components/schemas/Link'
        culture:
          type: string
          description: The culture code of the download order, for example `en-US`.
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
      description: Represents a download order.
    DownloadOrderTargetCollectionResource:
      type: object
      properties:
        order:
          $ref: '#/components/schemas/Link'
        items:
          type: array
          items:
            $ref: '#/components/schemas/DownloadOrderTargetResource'
          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: {}
    DownloadOrderTargetResource:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
    DownloadOrderType:
      enum:
        - Standard
        - Custom
      type: string
      description: The type of order, for example, `Standard` or `Custom`.
    IProcessingParameterValue:
      type: object
      additionalProperties: false
      description: Value for a processing parameter.
    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.
    OrderRequestResource:
      type: object
      properties:
        zip_filename:
          type: string
          description: The name of the ZIP file.
          nullable: true
        global:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RequestResource'
          description: >-
            Configuration of what to download by asset media group. For example,
            the rendition `MP4` for all videos, and the `medium` for all images.
            Asset media groups are identified by their ID.
          nullable: true
        individual:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RequestResource'
          description: >-
            Configuration of what to download for individual assets. To use when
            willing to download something different for specific assets than for
            the rest of the assets of the same media group. For example, to
            download the rendition `MP4` for a video asset with ID 1234, while
            for all other videos, the `Original` rendition will be downloaded
            through the `global` configuration.
          nullable: true
        isEmpty:
          type: boolean
          description: Whether the order is empty.
          readOnly: true
      additionalProperties: false
      description: The configuration to create an order.
    ProcessingParameter:
      enum:
        - fileExtension
        - colorSpace
        - resolution
        - bitrate
        - aspectRatio
        - dimension
        - colorProfile
        - clippingPath
        - resizeLogic
        - width
        - height
        - simple
        - filename
        - cropping
        - preset
        - trimStart
        - trimEnd
        - focalPoint
      type: string
      description: List of file processing attributes.
    RequestResource:
      type: object
      properties:
        renditions:
          type: array
          items:
            type: string
          description: The list of renditions to download.
          nullable: true
        conversions:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/ConversionParameterResource'
            description: Configuration for a conversion from an original file.
          description: >-
            Configuration to create a new conversion from the original file for
            the download.
          nullable: true
        user_rendition_configuration:
          $ref: '#/components/schemas/UserRenditionConfigurationResource'
        presets:
          type: array
          items:
            type: string
          description: List of predefined settings for the download order.
          nullable: true
      additionalProperties: false
      description: >-
        Configuration for the files to download either for an individual asset,
        or for all assets from the same media group.
    SelectionResource:
      type: object
      properties:
        selectionPool:
          type: string
          description: >-
            The identifier of the selection pool that contains the entities to
            download.
          nullable: true
        subPoolId:
          type: integer
          description: >-
            When a selection pool is page specific, the ID of the entity on the
            page. For example, in the case of a selection pool for the assets in
            a collection, the ID of the collection.
          format: int64
          nullable: true
        definitionName:
          type: string
          description: >-
            The definition name of the download order items, for example,
            `M.Asset`.
          nullable: true
      additionalProperties: false
      description: >-
        Describes what selection pool to use for an order. The selection pool
        contains the list of entities to download.
    UserRenditionConfigurationResource:
      type: object
      properties:
        label:
          type: string
          description: The label for the user rendition.
          nullable: true
        culture:
          type: string
          description: The culture code of the user rendition, for example `en-US`.
          nullable: true
        description:
          type: string
          description: A description of the user rendition.
          nullable: true
      additionalProperties: false
      description: Configuration to create a user rendition from the first conversion.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
