openapi: 3.0.1
info:
  title: Upload API
  description: >
    Use the Upload API to upload files to Content Hub. Uploads are completed in
    three steps:

     1. Generate an upload URL that returns metadata about the upload session. Provide the following information:
          - <b>Configuration</b> settings to use for the upload - an entity that hosts a predefined configuration, which specifies supported file extensions, the permitted file size, the default asset lifecycle for asset creation, and so on.

          - <b>Purpose</b> of the newly uploaded file - create a new asset, use the uploaded file as a new master file for an existing asset, or use the file as an alternate file for an existing asset.

     2. Upload the file to the generated upload URL.

     3. Complete the upload by providing the metadata about the session that was generated in step 1.

     For more information and to see examples, refer to the [Upload API documentation](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload-api.html). For details on how to upload large files, see [Upload large files](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload-large-files.html).

    {% admonition type="warning" name="Important" %}The Upload API is not
    intended for the bulk upload of assets. High volumes of parallel uploads can
    impact performance. Review [Performance best
    practices](https://doc.sitecore.com/ch/en/users/content-hub/performance.html)
    to ensure optimal performance of Content Hub.{% /admonition %}

    {% admonition type="info" name="Note" %}Security is applied at the upload
    configuration level. This means that the user upload permissions depend on
    the upload configuration entities that users have access to.{% /admonition
    %}

    ## Authentication

    To use the Upload 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
    your mouse 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 using 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: Upload
    description: 'The Upload endpoint is used to manage file uploads.  '
paths:
  /api/v2.0/upload:
    post:
      tags:
        - Upload
      summary: Generate an upload URL
      description: >-
        Generates a URL that can be used to upload a file based on the upload
        configuration provided. For security reasons, the URL is only valid for
        a limited time. When uploading a file, you must provide the
        configuration and action to be performed with the upload. <br /><br
        />When you upload a file, it can:<br />  - Create a new asset.<br />  -
        Create a new version of an existing asset.<br />  - Be an alternate file
        for an existing asset.<br /><br /> Uploads require an upload
        configuration that defines supported file extensions, the content
        repository to which the file is to be uploaded, and so on. Security
        checks validate that the user has permission to perform uploads. The
        upload URL is returned in the response `location` header.
      operationId: CreateUploadUrl
      requestBody:
        description: The context for the upload.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/FileUploadUrlRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadUrlRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/FileUploadUrlRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/FileUploadUrlRequest'
      responses:
        '201':
          description: The upload URl has been created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadUrlResource'
        '400':
          description: Request not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized request
        '403':
          description: User not allowed to perform an upload using the given context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Upload configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: An internal server error occurred
      security:
        - oauth2: []
  /api/v2.0/upload/process:
    post:
      tags:
        - Upload
      summary: Upload a file
      description: >-
        Uploads a file in chunks or as a whole. The URL is generated by the
        upload URL endpoint. When uploading in chunks, the current chunk number
        starts at 0 and the total number of chunks must be provided as a query
        string parameter. Multiple chunks can be uploaded in parallel. To notify
        that the last chunk has been uploaded and no more are expected, a final
        request needs to be made with only the parameter of the chunk.
      operationId: ProcessUpload
      parameters:
        - name: key
          in: query
          description: The file identifier.
          required: true
          schema:
            type: string
        - name: name
          in: query
          description: The file name.
          required: true
          schema:
            type: string
        - name: expires
          in: query
          description: >-
            The expiration date of the request after which the upload URL
            becomes invalid.
          required: true
          schema:
            type: string
            format: date-time
        - name: chunk
          in: query
          description: When uploading in chunks, the current chunk number.
          schema:
            type: integer
            format: int32
        - name: chunks
          in: query
          description: When uploading in chunks, the total number of chunks.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: File successfully uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResult'
        '400':
          description: Request not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Request has expired or user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: An internal server error occurred
  /api/v2.0/upload/finalize:
    post:
      tags:
        - Upload
      summary: Finalize the upload process for a file
      description: >-
        Finalizes the upload of a file after all chunks have been uploaded.
        Requires the metadata returned during the creation of the upload URL
        that identifies the current upload session. When finalizing the upload
        process, the `action` configured during the creation of the upload URL
        is performed.
      operationId: FinalizeUpload
      requestBody:
        description: The context of the upload returned when creating the upload URL.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/FinalizeUploadRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizeUploadRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/FinalizeUploadRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/FinalizeUploadRequest'
      responses:
        '200':
          description: Upload finalized successfully
        '400':
          description: Request not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized request
        '403':
          description: Upload has expired or user not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Upload job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: An internal server error occurred
      security:
        - oauth2: []
components:
  schemas:
    FileUploadUrlRequest:
      type: object
      properties:
        file_name:
          type: string
          description: The name of the file to be uploaded.
          nullable: true
        file_size:
          type: integer
          description: The size of the file to be uploaded.
          format: int64
        upload_configuration:
          $ref: '#/components/schemas/UploadConfigurationInfo'
        action:
          $ref: '#/components/schemas/UploadActionInfo'
      additionalProperties: false
      description: >-
        Information about the context of the upload when requesting an upload
        URL.
    FileUploadUrlResource:
      type: object
      properties:
        upload_identifier:
          type: string
          description: >-
            The identifier for the upload session. This is used later to
            complete the upload process, after the file has been uploaded.
          nullable: true
        storage_identifier:
          type: string
          description: >-
            The identifier of the upload storage. This is used later to complete
            the upload process after the file has been uploaded.
          nullable: true
        file_identifier:
          type: string
          description: >-
            This is used later to complete the upload process after the file has
            been uploaded.
          nullable: true
      additionalProperties: false
      description: >-
        Once an upload URL has been requested, the upload process is started.
        This information is required to finalize the process.
    FileUploadResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          nullable: true
      additionalProperties: false
    FinalizeUploadRequest:
      type: object
      properties:
        upload_identifier:
          type: string
          description: >-
            The identifier of the upload session returned during the request for
            the upload URL.
          nullable: true
        storage_identifier:
          type: string
          description: >-
            The identifier of the upload storage returned during the request for
            the upload URL.
          nullable: true
        file_identifier:
          type: string
          description: The file identifier returned during the request for the upload URL.
          nullable: true
      additionalProperties: false
      description: Request to finalize an upload process.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    UploadActionInfo:
      type: object
      properties:
        name:
          type: string
          description: >-
            The name of the action (`NewAsset`, `NewMainFile`, or
            `NewAlternativeFile`)
          nullable: true
        parameters:
          description: >-
            The parameters necessary for some actions. The action `NewMainFile`,
            or `NewAlternativeFile` requires the ID of the asset to which the
            file will be uploaded, such as `{"AssetId": 32052}`
          nullable: true
          type: object
      additionalProperties: false
    UploadConfigurationInfo:
      type: object
      properties:
        name:
          type: string
          description: The name of the upload configuration to use
          nullable: true
        parameters:
          description: >-
            The parameters necessary for some upload configurations. For
            example, an upload can directly link the asset to another entity
            upon creation, such as when uploading an asset for a product. In
            this case, the name of the relation between asset and product and
            the product ID is required as a parameter (for example `{
            "PCMProductToAsset" : 123} `).
          nullable: true
          type: object
      additionalProperties: false
      description: Information about the upload configuration.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
