Defined.ai (DefinedCrowd) Project Management API

openapi: 3.2.0
info:
  title: Defined.ai Project Management 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: Project Management
  description: 'Informally, projects can be viewed as configurable packages that process sets of Input Units. The project’s template determines how the Input Units are processed. Projects can be retrieved and managed as needed through the following methods:'
paths:
  /v2.0/public/projects/{sourceProjectId}/clone:
    post:
      tags:
      - Project Management
      summary: Clone Project
      description: 'Cloning a project creates a copy of the setup configuration and other elements.

        A new project with the same configuration, properties and jobs as the source project is created.


        **Permission Required:** Create Project'
      operationId: Projects_CloneProject
      parameters:
      - name: sourceProjectId
        in: path
        description: Source Project ID. The project is copied from this ID.
        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.CloneProjectConfigurationViewModel'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectConfigurationViewModel'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectConfigurationViewModel'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectConfigurationViewModel'
        required: true
      responses:
        '202':
          description: Accepted. Project will be cloned asynchronously.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectResult'
            application/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectResult'
            text/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectResult'
        '400':
          description: Invalid parameters.
        '401':
          description: Invalid authentication (invalid/expired token).
        '404':
          description: Source project does not exist.
  /v2.0/public/projects:
    get:
      tags:
      - Project Management
      summary: Get Projects
      description: 'Retrieves a comprehensive list of projects and the respective information about those projects associated

        with an Enterprise account. This includes Projects created through the REST API and the Enterprise Portal.


        **Permission Required:** List Projects'
      operationId: Projects_GetProjects
      parameters:
      - name: pageNumber
        in: query
        description: The page to retrieve.
        schema:
          type: integer
          format: int32
          default: 0
      - name: itemsPerPage
        in: query
        description: The number of items to retrieve per page. The maximum number of items per page allowed is 100.
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Returns a List with project Information.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetPagedProjectsQueryResults'
            application/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetPagedProjectsQueryResults'
            text/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetPagedProjectsQueryResults'
        '400':
          description: Invalid page number or items per page count
        '401':
          description: Invalid authentication (invalid/expired token).
        '403':
          description: Invalid Enterprise Subscription.
  /v2.0/public/projects/{projectId}:
    get:
      tags:
      - Project Management
      summary: Get Project Details
      description: 'Retrieves the information associated with a Project.


        **Permission Required:** Read Project Properties'
      operationId: Projects_GetProjectDetails
      parameters:
      - name: projectId
        in: path
        description: Project ID.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Returns project details.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetProjectDetailsResult'
            application/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetProjectDetailsResult'
            text/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetProjectDetailsResult'
        '401':
          description: Invalid authentication (invalid/expired token).
        '404':
          description: Project does not exist.
    put:
      tags:
      - Project Management
      summary: Edit Project
      description: 'Allows you to edit project settings such as name and desired delivery date, after creation or cloning.

        The editing function stops once the first upload of input units begin and the NOT ACTIVE project state

        is changed.


        Note: both fields must be provided to update either one of them.


        **Permission Required:** Update Project Properties'
      operationId: Projects_EditProject
      parameters:
      - name: projectId
        in: path
        description: Project ID.
        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.UpdateProject.UpdateProjectViewModel'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UpdateProject.UpdateProjectViewModel'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UpdateProject.UpdateProjectViewModel'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Models.Projects.UpdateProject.UpdateProjectViewModel'
        required: true
      responses:
        '202':
          description: Accepted. Project is updated asynchronously. No response body.
        '400':
          description: Invalid parameters.
        '401':
          description: Invalid authentication (invalid/expired token).
        '404':
          description: Project does not exist.
  /v2.0/public/projects/{projectId}/status:
    get:
      tags:
      - Project Management
      summary: Get Project Status
      description: 'When invoked, Get Project Status returns current project status and — if input data errors

        were detected — error information associated with each input data unit where an error occurred.


        A project’s state can change due to REST API calls executed by your code, changes made to a project in

        the Enterprise Portal as well as project-related events occurring at Defined.ai.

        It is not guaranteed that project states follow a sequential, ordered progression.


        | REST API Call Invocation | Project Related Event | Project Status | Invokable REST API Calls |

        |:-------------|:-------------|:-------------|:-------------|

        | Create Project | Project has been created | NOT ACTIVE | Upload Data Units

        Delete Project |

        | Upload Data Units | Defined.ai is running validation | PROCESSING DATA UPLOAD | |

        | | Upload to Defined.ai is complete and no errors were detected | UPLOAD SUCCESS | Upload Data Units

        Delete Project |

        | | Upload to Defined.ai is complete but Defined.ai found errors in some Input Units | UPLOAD ERRORS | Upload Data Units

        Delete Project |

        | | Upload to Defined.ai is complete but no data unit is valid | INSUFFICIENT DATA | Upload Data Units

        Delete Project |

        | | Defined.ai is preparing the project before deploying it to our human intelligence community | PREPARING PROJECT | Cancel Project |

        | | Defined.ai has deployed the project to our human intelligence community | RUNNING | Cancel Project |

        | | Defined.ai is accessing the quality of the human intelligence community | ASSESSING QUALITY | Cancel Project |

        | | Defined.ai is curating and preparing the results for download | GENERATING RESULTS | |

        | | Defined.ai has completed the project and data is available for download | PROJECT COMPLETED | Delete Project

        Get Deliverables |

        | Cancel Project | Defined.ai has canceled the project | CANCELLED | Delete Project |

        | Delete Project | Defined.ai has deleted the project | DELETED | |


        **Permission Required:** Read Project Properties'
      operationId: Projects_GetProjectStatus
      parameters:
      - name: projectId
        in: path
        description: Project identifier.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: The ProjectStatus structure.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetProjectStatusQueryResults'
            application/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetProjectStatusQueryResults'
            text/json:
              schema:
                $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.GetProjectStatusQueryResults'
        '401':
          description: Invalid authentication (project from another enterprise or invalid/expired token).
        '404':
          description: Project does not exist.
  /v2.0/public/projects/{projectId}/cancel:
    put:
      tags:
      - Project Management
      summary: Cancel Project
      description: 'Cancels a Project that has been Started. When Cancel is invoked, Defined.ai reviews the progress of the

        Project being canceled. If a portion of the Project has been completed, the Enterprise customer is charged

        for that portion, and refunded with the credits for the remainder of the uncompleted work.


        **Permission Required:** Update Project Properties'
      operationId: Projects_CancelProject
      parameters:
      - name: projectId
        in: path
        description: Project identifier.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Project cancelled.
        '400':
          description: Project status cannot be switched.
        '401':
          description: Invalid authentication (project from another enterprise or invalid/expired token).
        '403':
          description: Invalid Enterprise Subscription.
        '404':
          description: Project does not exist.
  /v2.0/public/projects/{projectId}/delete:
    delete:
      tags:
      - Project Management
      summary: Delete Project
      description: 'Deletes a Project. When a Project is deleted, it is no longer available. As a result, if the Project has

        been completed and there exists project results, we recommend that project results are retrieved prior to

        deletion.


        Quick tip: Projects can be deleted if they haven''t been started, if they were completed, paused or cancelled.


        **Permission Required:** Delete Project'
      operationId: Projects_DeleteProject
      parameters:
      - name: projectId
        in: path
        description: Project identifier.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Project deleted.
        '400':
          description: Project status cannot be switched.
        '401':
          description: Invalid authentication (project from another enterprise or invalid/expired token).
        '403':
          description: Invalid Enterprise Subscription.
        '404':
          description: Project does not exist.
components:
  schemas:
    DefinedCrowd.PublicApi.Api.Results.Project.ErrorProperty:
      title: JSON object
      type: object
      properties:
        inputDataUnitProperty:
          type:
          - string
          - 'null'
          description: Name of property for which error exists.
        inputDataUnitPropertyValue:
          type:
          - string
          - 'null'
          description: Original value of the property for which error exists.
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Results.Project.GetProjectDetailsResult:
      title: JSON object
      type: object
      properties:
        projectId:
          type: string
          description: Project ID.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        projectName:
          type:
          - string
          - 'null'
          description: Name of the project.
        dateTimeCreated:
          type: string
          description: Date and time when the project was created in UTC format.
          format: date-time
        desiredDeliveryDate:
          type:
          - string
          - 'null'
          description: Desired delivery date and time for new project in UTC format.
          format: date-time
        status:
          type:
          - string
          - 'null'
          description: The project's current status.
        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. Although there are no inherent types of metatags, they enable customers to categorize a project by purpose, owner, environment, or other criteria for administrative purposes. Defined.ai does not perform any actions on metatags that customers submit.\n\nThe 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\nBelow is an example of  a set of 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\"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    }"
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Results.Project.ProjectDetails:
      title: JSON object
      type: object
      properties:
        id:
          type: string
          description: Project Identifier.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        name:
          type:
          - string
          - 'null'
          description: Name of the project.
        projectType:
          type:
          - string
          - 'null'
          description: Code that identifies a project template type
        status:
          type:
          - string
          - 'null'
          description: The project's current status.
        dateTimeCreated:
          type: string
          description: Date and time when the project was created.
          format: date-time
        dateTimeLastRun:
          type:
          - string
          - 'null'
          description: Date and time when the project last ran.
          format: date-time
        progress:
          type: integer
          description: "Reflects the progress of execution of a specific project.\n            \nThis value is subject to changes. The progress might decrease as the latest collected data is still subject to quality validations."
          format: int32
        estimatedDateToComplete:
          type:
          - string
          - 'null'
          description: "A projection of the project completion date.\n            \nThis is not a committed date. The date is a projection based on the average speed at which data is collected and may vary."
          format: date-time
        totalNumberInputUnitsSubmitted:
          type: integer
          description: Total number of input units submitted for the project.
          format: int32
        totalNumberOutputUnitsCompleted:
          type: integer
          description: Number of data units already completed.
          format: int32
        targetNumberOutputDataUnits:
          type: integer
          description: Number of target data units.
          format: int32
        uploadInputUnitsError:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.UploadInputUnitError'
          description: List of errors in the data unit uploading asynchronous process.
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Results.Project.UploadInputUnitError:
      title: JSON object
      type: object
      properties:
        inputDataUnitId:
          type: string
          description: Unique identifier of the input data unit where the error occurred.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        errorType:
          enum:
          - connectionUnsuccessful
          - fileDoesNotExist
          - fileIsNotValid
          - unauthorizedAccess
          - statusCodeDoesNotIndicateSuccess
          - platformError
          - urlNotSupported
          type: string
          description: Type of error.
          x-enumNames:
          - ConnectionUnsuccessful
          - FileDoesNotExist
          - FileIsNotValid
          - UnauthorizedAccess
          - StatusCodeDoesNotIndicateSuccess
          - PlatformError
          - UrlNotSupported
          x-enumDescriptions:
          - ''
          - ''
          - ''
          - ''
          - ''
          - ''
          - ''
          x-ms-enum:
            name: FileUploadErrorMessage
            modelAsString: true
        errorDetails:
          type:
          - string
          - 'null'
          description: Details of error.
        errorProperty:
          allOf:
          - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.ErrorProperty'
        inputDataUnit:
          description: Fields of the original uploaded input unit.
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Results.Project.ProjectInfo:
      title: JSON object
      type: object
      properties:
        id:
          type: string
          description: Project Identifier.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        name:
          type:
          - string
          - 'null'
          description: Name of the project.
        projectType:
          type:
          - string
          - 'null'
          description: Code that identifies a project template type
        status:
          type:
          - string
          - 'null'
          description: The project's current status.
        dateTimeCreated:
          type: string
          description: Date and time when the project was created.
          format: date-time
        dateTimeLastRun:
          type:
          - string
          - 'null'
          description: Date and time when the project last ran.
          format: date-time
        totalNumberInputUnitsSubmitted:
          type: integer
          description: Total number of input units submitted for the project.
          format: int32
        totalNumberOutputUnitsCompleted:
          type: integer
          description: Total number of data units already completed.
          format: int32
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Models.Projects.UpdateProject.UpdateProjectViewModel:
      title: JSON object
      required:
      - desiredDeliveryDate
      - metatags
      - projectName
      type: object
      properties:
        projectName:
          maxLength: 80
          minLength: 0
          type: string
          description: Name of project.
        desiredDeliveryDate:
          type:
          - string
          - 'null'
          description: Desired date of delivery for project in UTC format <yyyy-mm-dd>. If left as null, no desired delivery date is assigned.
          format: date
        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     }"
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Results.Project.GetPagedProjectsQueryResults:
      title: JSON object
      type: object
      properties:
        projects:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.ProjectInfo'
          description: A page with details from several projects.
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectConfigurationViewModel:
      title: JSON object
      required:
      - projectName
      type: object
      properties:
        projectName:
          maxLength: 80
          minLength: 0
          type: string
          description: New project name.
        desiredDeliveryDate:
          type:
          - string
          - 'null'
          description: "Desired delivery date for new project in UTC format <yyyy-mm-dd>. \nIf left as null, no desired delivery date is assigned."
          format: date
        targetProjectId:
          type:
          - string
          - 'null'
          description: New project ID. If left as null, GUID is auto-generated and returned in the response.
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        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     }"
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Results.Project.GetProjectStatusQueryResults:
      title: JSON object
      type: object
      properties:
        projectDetails:
          allOf:
          - $ref: '#/components/schemas/DefinedCrowd.PublicApi.Api.Results.Project.ProjectDetails'
          description: Details from a specific project.
      additionalProperties: false
    DefinedCrowd.PublicApi.Api.Models.Projects.CloneProject.CloneProjectResult:
      title: JSON object
      type: object
      properties:
        targetProjectId:
          type: string
          description: New project ID
          format: uuid
          readOnly: true
          example: 00000000-0000-0000-0000-000000000000
      additionalProperties: false
  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