Nuance Versions API

openapi: 3.2.0
info:
  title: Mix.api Specification Versions API
  version: 26.1026.216
security:
- OAuth2:
  - mix-api
  bearerAuth: []
tags:
- name: Versions
paths:
  /v4/projects/{projectId}/.version-format:
    post:
      summary: Set version format
      description: Set the version format for the project specified.
      operationId: MixAPI_SetProjectVersionFormat
      responses:
        '200':
          description: Version format
          content:
            application/json:
              schema:
                type: array
                $ref: '#/components/schemas/mix.api.SetProjectVersionFormatResponse'
        '400':
          description: Bad request; for example, project does not support versioning and workstreams
          content:
            application/json:
              schema: {}
        '401':
          description: Request could not be authorized
          content:
            application/json:
              schema: {}
        '404':
          description: Project not found
          content:
            application/json:
              schema: {}
        '500':
          description: Internal server error
          content:
            application/json:
              schema: {}
        '501':
          description: Feature is not yet enabled
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: projectId
        description: ID of the project.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Versions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/mix.api.SetProjectVersionFormatRequestPayload'
        description: Object used to set the project version.
        required: true
  /v4/projects/{projectId}/versions:
    get:
      summary: Get list of versions
      description: 'Retrieve the list of versions for a project.


        You can limit the number of results returned and use an offset to determine the starting position of results returned.'
      operationId: MixAPI_ListVersions
      responses:
        '200':
          description: List of versions
          content:
            application/json:
              schema:
                type: array
                $ref: '#/components/schemas/mix.api.ListVersionsResponse'
        '400':
          description: Bad request; for example, project does not support versioning and workstreams
          content:
            application/json:
              schema: {}
        '401':
          description: Request could not be authorized
          content:
            application/json:
              schema: {}
        '404':
          description: Project not found
          content:
            application/json:
              schema: {}
        '500':
          description: Internal server error
          content:
            application/json:
              schema: {}
        '501':
          description: Feature is not yet enabled
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: projectId
        description: ID of the project.
        in: path
        required: true
        schema:
          type: string
      - name: limit
        description: Maximum number of query results returned.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        description: Offset to use when returning results.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      tags:
      - Versions
  /v4/projects/{projectId}/versions/{versionName}:
    get:
      summary: Get version details
      description: Retrieve the details of a version.
      operationId: MixAPI_GetProjectVersion
      responses:
        '200':
          description: Version details
          content:
            application/json:
              schema:
                type: array
                $ref: '#/components/schemas/mix.api.GetProjectVersionResponse'
        '400':
          description: Bad request; for example, project does not support versioning and workstreams
          content:
            application/json:
              schema: {}
        '401':
          description: Request could not be authorized
          content:
            application/json:
              schema: {}
        '404':
          description: Project not found
          content:
            application/json:
              schema: {}
        '500':
          description: Internal server error
          content:
            application/json:
              schema: {}
        '501':
          description: Feature is not yet enabled
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: projectId
        description: ID of the project.
        in: path
        required: true
        schema:
          type: string
      - name: versionName
        description: Version name.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Versions
    delete:
      summary: Delete a version
      description: Delete a version.
      operationId: MixAPI_DeleteVersion
      responses:
        '200':
          description: Version was successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
        '400':
          description: Bad request; for example, the version is used by a build
          content:
            application/json:
              schema: {}
        '401':
          description: Request could not be authorized
          content:
            application/json:
              schema: {}
        '404':
          description: Project not found
          content:
            application/json:
              schema: {}
        '500':
          description: Internal server error
          content:
            application/json:
              schema: {}
        '501':
          description: Feature is not yet enabled
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: projectId
        description: ID of the project.
        in: path
        required: true
        schema:
          type: string
      - name: versionName
        description: Version name.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Versions
    put:
      summary: Update a version
      description: Update a version's properties.
      operationId: MixAPI_UpdateVersion
      responses:
        '200':
          description: Updated version details
          content:
            application/json:
              schema:
                type: array
                $ref: '#/components/schemas/mix.api.UpdateVersionResponse'
        '400':
          description: Bad request; for example, project does not support versioning and workstreams
          content:
            application/json:
              schema: {}
        '401':
          description: Request could not be authorized
          content:
            application/json:
              schema: {}
        '404':
          description: Project not found
          content:
            application/json:
              schema: {}
        '500':
          description: Internal server error
          content:
            application/json:
              schema: {}
        '501':
          description: Feature is not yet enabled
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: projectId
        description: ID of the project.
        in: path
        required: true
        schema:
          type: string
      - name: versionName
        description: Version name.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Versions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/mix.api.UpdateVersionRequestPayload'
        description: Object used to update a version.
        required: true
  /v4/projects/{projectId}/versions/{versionName}/.rename:
    put:
      summary: Rename a version
      description: Rename a version.
      operationId: MixAPI_RenameVersion
      responses:
        '200':
          description: Renamed version
          content:
            application/json:
              schema:
                type: array
                $ref: '#/components/schemas/mix.api.RenameVersionResponse'
        '400':
          description: Bad Request; for example, project does not support versioning and workstreams, version is used by any build, and so on
          content:
            application/json:
              schema: {}
        '401':
          description: Request could not be authorized
          content:
            application/json:
              schema: {}
        '404':
          description: Project not found
          content:
            application/json:
              schema: {}
        '500':
          description: Internal server error
          content:
            application/json:
              schema: {}
        '501':
          description: Feature is not yet enabled
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: projectId
        description: ID of the project.
        in: path
        required: true
        schema:
          type: string
      - name: versionName
        description: Version name.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Versions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/mix.api.RenameVersionRequestPayload'
        description: Object used to rename a version.
        required: true
components:
  schemas:
    mix.api.RenameVersionRequestPayload:
      type: object
      properties:
        newName:
          type: string
          description: New version name.
      description: Object used to rename a version.
    mix.api.GetProjectVersionResponse:
      type: object
      example:
        version:
          name: 3.6.0
          description: tag 3.6.0
          createTime: '2022-06-08T21:10:37.456Z'
          createdBy:
            name: Sam Karan
            email: sam.karan@abc.com
      properties:
        version:
          $ref: '#/components/schemas/mix.api.SnapshotVersion'
          description: Snapshot version.
      description: Response object used by the Get version details request.
    mix.api.UpdateVersionResponse:
      type: object
      example:
        version:
          name: 3.6.0
          description: tag 3.6.0
          createTime: '2022-06-08T21:10:37.456Z'
          createdBy:
            name: Sam Karan
            email: sam.karan@abc.com
      properties:
        version:
          $ref: '#/components/schemas/mix.api.SnapshotVersion'
          description: Snapshot version.
      description: Response object used by the Update version request.
    google.protobuf.Any:
      type: object
      properties:
        type_url:
          type: string
          description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n  value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n  URL, or have them precompiled into a binary to avoid any\n  lookup. Therefore, binary compatibility needs to be preserved\n  on changes to types. (Use versioned type names to manage\n  breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
        value:
          type: string
          format: byte
          description: Must be a valid serialized protocol buffer of the above specified type.
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n    // or ...\n    if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n      foo = any.unpack(Foo.getDefaultInstance());\n    }\n\n Example 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\n Example 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := anypb.New(foo)\n     if err != nil {\n       ...\n     }\n     ...\n     foo := &pb.Foo{}\n     if err := any.UnmarshalTo(foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }"
    mix.api.UpdateVersionRequestPayload:
      type: object
      properties:
        description:
          type: string
          description: Version description.
      description: Object used to update a version.
    mix.api.RenameVersionResponse:
      type: object
      example:
        version:
          name: 3.9.0
          description: old description
          createTime: '2022-06-08T21:10:37.456Z'
          createdBy:
            name: Sam Karan
            email: sam.karan@abc.com
      properties:
        version:
          $ref: '#/components/schemas/mix.api.SnapshotVersion'
          description: Snapshot version.
      description: Response object used by the Rename version request.
    grpc.gateway.runtime.Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
    mix.api.Author:
      type: object
      properties:
        name:
          type: string
          description: Author name.
        email:
          type: string
          description: Author email.
      description: Message that defines the user that authored a resource.
    mix.api.VersionFormat:
      type: string
      enum:
      - NO_VALUE_SET
      - SEMVER
      - FREEFORM
      default: NO_VALUE_SET
      description: "ENUM that defines the version naming format.\n\n - NO_VALUE_SET: No value set.\n - SEMVER: Semver version naming (for example, 3.1.0). Recommended as is provides better organization.\n - FREEFORM: Freeform version naming. Not recommended and some features may not be available."
    google.rpc.Status:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
        message:
          type: string
          description: 'A developer-facing error message, which should be in English. Any

            user-facing error message should be localized and sent in the

            [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.'
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
          description: 'A list of messages that carry the error details.  There will be a

            common set of message types for APIs to use.'
      description: "- Simple to use and understand for most users\n- Flexible enough to meet unexpected needs\n\n# Overview\n\nThe `Status` message contains three pieces of data: error code, error message,\nand error details. The error code should be an enum value of\n[google.rpc.Code][google.rpc.Code], but it may accept additional error codes if needed.  The\nerror message should be a developer-facing English message that helps\ndevelopers *understand* and *resolve* the error. If a localized user-facing\nerror message is needed, put the localized message in the error details or\nlocalize it in the client. The optional error details may contain arbitrary\ninformation about the error. There is a predefined set of error detail types\nin the package `google.rpc` which can be used for common error conditions.\n\n# Language mapping\n\nThe `Status` message is the logical representation of the error model, but it\nis not necessarily the actual wire format. When the `Status` message is\nexposed in different client libraries and different wire protocols, it can be\nmapped differently. For example, it will likely be mapped to some exceptions\nin Java, but more likely mapped to some error codes in C.\n\n# Other uses\n\nThe error model and the `Status` message can be used in a variety of\nenvironments, either with or without APIs, to provide a\nconsistent developer experience across different environments.\n\nExample uses of this error model include:\n\n- Partial errors. If a service needs to return partial errors to the client,\n    it may embed the `Status` in the normal response to indicate the partial\n    errors.\n\n- Workflow errors. A typical workflow has multiple steps. Each step may\n    have a `Status` message for error reporting purpose.\n\n- Batch operations. If a client uses batch request and batch response, the\n    `Status` message should be used directly inside batch response, one for\n    each error sub-response.\n\n- Asynchronous operations. If an API call embeds asynchronous operation\n    results in its response, the status of those operations should be\n    represented directly using the `Status` message.\n\n- Logging. If some API errors are stored in logs, the message `Status` could\n    be used directly after any stripping needed for security/privacy reasons."
      title: 'The `Status` type defines a logical error model that is suitable for different

        programming environments, including REST APIs and RPC APIs. It is used by

        [gRPC](https://github.com/grpc). The error model is designed to be:'
    mix.api.SetProjectVersionFormatResponse:
      type: object
      example:
        versionFormat: SEMVER
      properties:
        versionFormat:
          $ref: '#/components/schemas/mix.api.VersionFormat'
          description: Version format.
      description: Response object used by the Set project version format request.
    mix.api.SetProjectVersionFormatRequestPayload:
      type: object
      properties:
        versionFormat:
          $ref: '#/components/schemas/mix.api.VersionFormat'
          description: Version format.
      description: Object used to set the project version.
    mix.api.SnapshotVersion:
      type: object
      properties:
        name:
          type: string
          description: Version name.
        description:
          type: string
          description: Version description.
        snapshotId:
          type: string
          description: Snapshot ID.
        createTime:
          type: string
          format: date-time
          description: Version creation time.
        createdBy:
          $ref: '#/components/schemas/mix.api.Author'
          description: User who created version.
      description: Message that defines the snapshot version.
    mix.api.ListVersionsResponse:
      type: object
      example:
        versions:
        - name: 3.6.0
          description: tag 3.6.0
          createTime: '2022-06-08T21:10:37.456Z'
          createdBy:
            name: Sam Karan
            email: sam.karan@abc.com
      properties:
        versions:
          type: array
          items:
            $ref: '#/components/schemas/mix.api.SnapshotVersion'
          description: List of snapshot versions for the project.
        limit:
          type: integer
          format: int32
          description: Value of limit field specified in request.
        offset:
          type: integer
          format: int32
          description: Value of offset field specified in request.
      description: Response object used by the Get list of versions request.
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            mix-api: Grants access to mix-api
          tokenUrl: /oauth2/token
    bearerAuth:
      type: apiKey
      name: Authorization
      in: header