Defined.ai (DefinedCrowd) Mean Opinion Score API

openapi: 3.2.0
info:
  title: Defined.ai Mean Opinion Score API
  description: '# Introduction


    Welcome to the Defined.ai Public API.'
  version: v2
  x-logo:
    url: https://definedcrowd.azureedge.net/content/images/dai-logo-black.svg
    backgroundColor: '#FFFFFF'
    href: https://defined.ai/
security:
- Bearer: []
tags:
- name: Mean Opinion Score
  description: Aggregate ratings on the "intelligibility" and "naturalness" of utterances.
paths:
  /v2.0/public/projects/MeanOpinionScore:
    post:
      tags:
      - Mean Opinion Score
      summary: Create Project
      description: 'Creates a Mean Opinion Score project with a specific type and respective options.


        **Permission Required:** Create Projects'
      operationId: MeanOpinionScoreProject_CreateProject
      requestBody:
        description: ''
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.CreateProjectViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreProjectConfigViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.CreateProjectViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreProjectConfigViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.CreateProjectViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreProjectConfigViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.CreateProjectViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreProjectConfigViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
        required: true
      responses:
        '200':
          description: Project was successfully created.
        '400':
          description: Project Options are invalid.
        '401':
          description: User is not authorized (invalid/expired token).
  /v2.0/public/projects/MeanOpinionScore/{projectId}/inputUnits:
    post:
      tags:
      - Mean Opinion Score
      summary: Upload input units
      description: '|The endpoint will be deprecated


        The uploading of input units is an asynchronous process.

        Our API performs a variety of syntax evaluations upon method invocation and will return syntax-type errors

        immediately.

        If the uploaded input units passes syntax evaluations, the Project state will change to PROCESSING DATA UPLOAD.

        Errors found during asynchronous processing of the uploaded input units will change the Project state to UPLOAD

        ERRORS.

        To retrieve the specific errors for each input unit call Get Project Status.


        **Permission Required:** Upload Data'
      operationId: MeanOpinionScoreProject_UploadProjectInputUnits
      parameters:
      - name: projectId
        in: path
        description: Project identifier.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      requestBody:
        description: ''
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.UploadInputUnitsViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.InnerObjects.UploadAudioInputUnitViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.UploadInputUnitsViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.InnerObjects.UploadAudioInputUnitViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.UploadInputUnitsViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.InnerObjects.UploadAudioInputUnitViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.UploadInputUnitsViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.InnerObjects.UploadAudioInputUnitViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null'
        required: true
      responses:
        '200':
          description: Input Units were successfully added.
        '400':
          description: 'Not enough data units.

            Invalid input parameters.'
        '401':
          description: Invalid authentication (project from another enterprise or invalid/expired token).
        '403':
          description: 'Project not accepting more input units.

            Invalid Enterprise Subscription.'
        '404':
          description: Project does not exist.
      deprecated: true
  /v2.0/public/projects/MeanOpinionScore/{projectId}/resultset:
    get:
      tags:
      - Mean Opinion Score
      summary: Get Result Set
      description: 'Gets result set for the entire project.


        **Permission Required:** Read Project Properties'
      operationId: MeanOpinionScoreProject_GetProjectResultSet
      parameters:
      - name: projectId
        in: path
        description: Project identifier.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: URL to the file containing the results of the project.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.GetProjectResultSetQueryResults'
              example:
                resultsFileUrl: https://someurl/DC/resultset.json
            application/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.GetProjectResultSetQueryResults'
              example:
                resultsFileUrl: https://someurl/DC/resultset.json
            text/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.GetProjectResultSetQueryResults'
              example:
                resultsFileUrl: https://someurl/DC/resultset.json
        '400':
          description: Invalid page number or items per page count
        '401':
          description: Invalid authentication (project from another enterprise or invalid/expired token).
        '403':
          description: Invalid Enterprise Subscription.
        '404':
          description: Project does not exist or results do not exist.
  /v2.0/public/projects/MeanOpinionScore/{projectId}/clone:
    post:
      tags:
      - Mean Opinion Score
      summary: Clone project
      description: 'Retrieves the project configuration, then creates a new project with the retrieved configuration.


        **Permission Required:** Create Projects, Read Project Properties'
      operationId: MeanOpinionScoreProject_CloneProjectConfiguration
      parameters:
      - name: projectId
        in: path
        description: Project identifier.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      requestBody:
        description: ''
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectViewModel'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectViewModel'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectViewModel'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectViewModel'
        required: true
      responses:
        '200':
          description: Project was successfully cloned.
        '400':
          description: Project Options are invalid.
        '401':
          description: User is not authorized (invalid/expired token).
        '404':
          description: Project not found.
components:
  schemas:
    DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.LanguageConfigurationViewModel:
      title: JSON object
      required:
      - languageCode
      type: object
      properties:
        languageCode:
          minLength: 1
          type: string
          description: Language code. (e.g. "en-us")
        requireLanguageTest:
          type:
          - boolean
          - 'null'
          description: 'If selected, the project requires the contributors to do a language test

            (if available for the selected language) to guarantee that they are native speakers.'
          default: false
      additionalProperties: false
      description: Language configurations.
    DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.ContributorsDistributionViewModel:
      title: JSON object
      type: object
      properties:
        ageDistribution:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.Demographics.AgeDistributionViewModel'
          description: Age Distribution
        genderDistribution:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.Demographics.GenderDistributionViewModel'
          description: Gender Distribution
        deviceLocationDistribution:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.Demographics.DeviceLocationDistributionViewModel'
          description: Device Location Distribution
      additionalProperties: false
      description: "Configure the contributors' distribution to meet your requirements.\n            \n**Disclaimer**\n            \nThough every effort is made to meet the contributors’ distribution as\nconfigured, sometimes, due to factors beyond the control of DefinedCrowd,\nwe need to implement a next-best solution and cannot guarantee a 100%\nmatch."
    DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.Demographics.GenderDistributionViewModel:
      title: JSON object
      type: object
      properties:
        target:
          enum:
          - Male
          - Female
          type: string
          description: 'The gender category makes provision for biological sexes female and male.

            Though third gender preference are respected as a choice, we would like to

            confirm biological sex of contributors.'
          x-enumNames:
          - Male
          - Female
          x-enumDescriptions:
          - ''
          - ''
          x-ms-enum:
            name: GenderDistributionRange
            modelAsString: true
        value:
          maximum: 100
          minimum: 1
          type: integer
          description: "**Custom distribution**\n            \nMeans the value is set to greater than 0% but\nsmaller than or equal to 100%. Should the total value\nbe set to less than 100%, the remaining percentage\nis set with the default distribution.\n            \n**Default distribution**\n            \nMeans that the values are randomized but comply with the job\nconfiguration. For example, language settings are taken into\nconsideration, as well as country and region settings. Without any\ncontributors’ distribution restriction, whoever is qualified may\nenter the job.\n            \n**Example**\n            \nJohn Doe sets the gender distribution to 75% of the participants\nbeing in the Female category. The remaining 25% will be randomly\ndistributed between the gender categories. Therefore, John must be\naware that some of the 25% random distribution may also include the\nFemale category."
          format: int32
      additionalProperties: false
      description: Gender Distribution
    DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectViewModel:
      title: JSON object
      type: object
      properties:
        projectName:
          type:
          - string
          - 'null'
          description: If left as null, a name will be generated from the original plus a timestamp.
        projectId:
          type: string
          description: A ID by which new project will be identified.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      additionalProperties: false
    ? DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.UploadInputUnitsViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.InnerObjects.UploadAudioInputUnitViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null
    : title: JSON object
      required:
      - inputUnitDetails
      type: object
      properties:
        inputUnitDetails:
          type: array
          items:
            $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.InnerObjects.UploadAudioInputUnitViewModel'
          description: List of input units.
        autoStartOnUploadSuccess:
          type:
          - boolean
          - 'null'
          description: 'Your project will automatically start once all data input units

            were successfully uploaded and the project status is UPLOAD SUCCESS'
          default: false
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreJobSettingsViewModel:
      title: JSON object
      required:
      - languageConfiguration
      type: object
      properties:
        contributorsDistribution:
          allOf:
          - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.ContributorsDistributionViewModel'
          description: "Configure the contributors' distribution to meet your requirements.\n            \n**Disclaimer**\n            \nThough every effort is made to meet the contributors’ distribution as\nconfigured, sometimes, due to factors beyond the control of Defined.ai,\nwe need to implement a next-best solution and cannot guarantee a 100%\nmatch."
        languageConfiguration:
          allOf:
          - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.LanguageConfigurationViewModel'
          description: Language configuration
        contributorsPerInputUnit:
          maximum: 5000
          minimum: 5
          type:
          - integer
          - 'null'
          description: 'ContributorsPerInputUnit determines how many contributors you would like to process that input unit.

            This will allow you to compare executions of the same input unit.'
          format: int32
          default: 15
        showDataDisclaimer:
          type: boolean
          description: Displays a disclaimer to specify that inputs are "Not Customer Data" (displayed within task U.I.)
          default: false
      additionalProperties: false
      description: Mean Opinion Score testing settings
    DefinedCrowd.PublicApi.Api.Models.Projects.UploadInputUnits.InnerObjects.UploadAudioInputUnitViewModel:
      title: JSON object
      required:
      - audioFileUrl
      type: object
      properties:
        audioFileUrl:
          type: string
          description: URL to the audio file that is going to be listened by the contributors.
          format: uri
        id:
          type:
          - string
          - 'null'
          description: Client generated identifier that will be used as InputUnit Id.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        details:
          maxLength: 500
          type:
          - string
          - 'null'
          description: Client generated additional meta-data. An optional string with at most 500 characters.
      additionalProperties: false
    ? DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.CreateProjectViewModel_1__DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreProjectConfigViewModel__DefinedCrowd.PublicApi.Api__Version_1.0.0.0__Culture_neutral__PublicKeyToken_null
    : title: JSON object
      required:
      - config
      - id
      - name
      type: object
      properties:
        id:
          type: string
          description: Client generated identifier that will be used as Project Id.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        name:
          maxLength: 80
          minLength: 0
          type: string
          description: Project name.
        config:
          allOf:
          - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreProjectConfigViewModel'
          description: Json structure with the project configuration.
        metatags:
          title: JSON object
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: " Metatags provide for the ability to assign metadata to projects in the form of key-value pairs.\n Although there are no inherent types of metatags, they enable customers to categorize a project by purpose, owner, environment, or other criteria.\n Defined.ai does not perform any actions on metatags that customers submit. DO NOT SUBMIT PERSONALLY IDENTIFIABLE INFORMATION (PII) in a Metatag.\n\n If left as null, no metatags are assigned.\n \n When set, the root-level properties support string, object, and array data types (data types do not belong to these three will be converted to string type), while properties at inner level support all valid JSON data types.\n  \n Below is an example on how to use metatags:\n \n    { \n         \"rootString\":  \"This is a string\",\n         \"rootObject\":  {\n \t\t\t\"innerBoolean\": true,\n \t\t\t\"innerNumber\": 1,\n \t\t\t\"innerString\": \"This is another string\",\n\t\t\t\t\"innerNull\": null,\n \t\t\t\"innerObject\": {\n \t\t\t\t},\n \t\t\t\"innerArray\": []\n \t\t},\n         \"rootArray\": [1, 2, 3, 4]\n     }"
        desiredDeliveryDate:
          type:
          - string
          - 'null'
          description: This field is for you to inform DC the desired date for Data to be delivered.
          format: date-time
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Results.GetProjectResultSetQueryResults:
      title: JSON object
      type: object
      properties:
        resultsFileUrl:
          type:
          - string
          - 'null'
          description: URL to the file containing the results of the project.
          format: uri
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreProjectConfigViewModel:
      title: JSON object
      required:
      - meanOpinionScore
      type: object
      properties:
        meanOpinionScore:
          allOf:
          - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.MeanOpinionScoreTesting.MeanOpinionScoreJobSettingsViewModel'
          description: Mean Opinion Score settings.
      additionalProperties: false
      description: Json structure with the project configuration.
    DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.Demographics.DeviceLocationDistributionViewModel:
      title: JSON object
      type: object
      properties:
        target:
          type:
          - string
          - 'null'
          description: 'Geolocation technology will give an approximate real-world

            geographic location of the device being used and thus the location

            of the contributor using the device.'
        value:
          maximum: 100
          minimum: 1
          type: integer
          description: "The value is set to greater than 0% but smaller than or equal to\n100%. Should the total value be set to less than 100%, the remaining\npercentage will have no constraints.\n            \n**Example**\n            \nJane Doe sets the device location distribution to 75% of the\nparticipants being in a particular geographic location. The\nremaining 25% will be randomly distributed. Therefore, Jane Doe\nmust be aware that some of the 25% random distribution may also\ninclude the particular geographic location that was set."
          format: int32
      additionalProperties: false
      description: Device Location Distribution
    DefinedCrowd.PublicApi.Api.Models.Projects.CreateProject.Common.Demographics.AgeDistributionViewModel:
      title: JSON object
      type: object
      properties:
        target:
          enum:
          - Adult
          - Senior
          type: string
          description: 'There are two age categories in the distribution.

            You can select Adult or Senior with age categories 18 – 64 years

            and 65 years and above, respectively.'
          x-enumNames:
          - Adult
          - Senior
          x-enumDescriptions:
          - ''
          - ''
          x-ms-enum:
            name: AgeDistributionRange
            modelAsString: true
        value:
          maximum: 100
          minimum: 1
          type: integer
          description: "**Custom distribution**\n            \nMeans the value is set to greater than 0% but\nsmaller than or equal to 100%. Should the total value\nbe set to less than 100%, the remaining percentage\nis set with the default distribution.\n            \n**Default distribution**\n            \nMeans that the values are randomized but comply with\nthe job configuration. For example, language settings\nare taken into consideration, as well as country and\nregion settings. Without any contributors’ distribution\nrestriction, whoever is qualified may enter the job.\n            \n**Examples**\n            \nJane Doe sets the age distribution to 75% of the participants being\nin the Adult category. The remaining 25% will be randomly distributed\nbetween the age categories. Therefore, Jane must be aware that some\nof the 25% random distribution may also include the Adult category."
          format: int32
      additionalProperties: false
      description: Age Distribution
  securitySchemes:
    Bearer:
      type: apiKey
      description: Please enter into field the word 'Bearer' following by space and JWT
      name: Authorization
      in: header
x-tagGroups:
- name: ' '
  tags:
  - Supported Languages
- name: Project life cycle
  tags:
  - Project Management
  - Subscriptions
  - Jobs
  - Input Units
  - Deliverables
- name: Speech Technologies
  tags:
  - Mean Opinion Score
  - Pronunciation Validation