tca-openapi.yaml

openapi: 3.0.1
info:
  title: Turnitin Core API
  description: |
    Turnitin Core API (TCA) provides direct API access to the core functionality provided by Turnitin. TCA supports file submission, similarity report generation, group management, and visualization of report matches via Cloud Viewer or PDF download.
    Below is the full flow to successfully set up an integration scope, an API Key, and make calls to TCA. Integration Scope and API Key management is done via the Admin Console UI by logging in as an admin user. For more details, go to our [developer portal documentation page](https://developers.turnitin.com/docs).
    ## Integration Scope and API Key Management
    TCA API calls must provide an API Key for authentication, so you must first have at least one integration scope associated with at least one API Key to use TCA.
    ### Admin Console UI
    First, login to Admin Console UI as an *Admin* user with permission to create Integration Scopes, under a tenant that is licensed to use the TCA product
    Integration Scopes (you can create a new one, or add keys to existing)

      * Click `Integrations` in the side bar --> `+ Add Integration` at top the top of the page --> Enter a name --> `Add` Button
      API Keys
      * Click `Integrations` in the side bar --> `Create API Key` Button next to a given Integration Scope -->
      Enter a name --> click `Create and View button`
      * Copy/Save the key manually or click save to clipboard button to copy it (this is the only time it will show)

    ## TCA Flow

      *  Register a webhook
      *  Create a submission
      *  Upload a file for the submission
      *  Wait for the submission upload to process
         * If you registered a webhook, a callback will be sent to it when upload is complete
         * The status of the *submission* will also update to `COMPLETE`
      *  Request a Similarity Report
      *  Wait for similarity report to process
         * If you registered a webhook, a callback will be sent to it when report is complete
         * The status of the *report* will also be updated to `COMPLETE`
      *  Request a URL with parameters to view the Similarity Report
  version: 1.0.258
externalDocs:
  description: Developer Portal Documentation page
  url: https://developers.turnitin.com/docs
servers:
  - url: https://{tenantName}.turnitin.com/api/v1
    variables:
      tenantName:
        default: app-us
        description: Customer tenant name
security:
  - api_key: []
tags:
  - name: Features
    description: Get license and feature information
  - name: EULA
    description: Manage acceptence of EULAs
  - name: Groups
    description: Used for template exclusion
  - name: Submission
    description: Upload files and retrieve data
  - name: Similarity
    description: Schedule and receive similarity report details
  - name: Webhook
    description: Create and manage Webhooks
paths:
  /features-enabled:
    get:
      tags:
        - Features
      summary: Get information about what features are allowed by the current license
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
      responses:
        200:
          description: List of available features
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturesEnabled'
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /eula/{version_id}:
    get:
      tags:
        - EULA
      summary: Gets information about a particular EULA version
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: version_id
          in: path
          description: |
            The EULA version ID (or `latest`)
          required: true
          schema:
            type: string
          example: latest
        - name: lang
          in: query
          description: The desired language of the specified EULA version
          schema:
            type: string
          example: en-US
      responses:
        200:
          description: Version data. A null value for valid_until indicates no expiration of the EULA version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EulaVersion'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /eula/{version_id}/accept:
    post:
      tags:
        - EULA
      summary: Accepts a particular EULA version on behalf of an external user
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: version_id
          in: path
          description: |
            The EULA version ID (or `latest`)
          required: true
          schema:
            type: string
          example: latest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EulaAcceptRequest'
        required: true
      responses:
        200:
          description: A EULA acceptence response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EulaAcceptListItem'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /eula/{version_id}/accept/{user_id}:
    get:
      tags:
        - EULA
      summary: Queries the acceptences of a particular EULA version on behalf of an external user
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: version_id
          in: path
          description: |
            The EULA version ID (or `latest`)
          required: true
          schema:
            type: string
          example: latest
        - name: user_id
          in: path
          description: |
            The user associated with the EULA status
          required: true
          schema:
            type: string
      responses:
        200:
          description: Array of EULA acceptence responses for the specified version (one per language)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EulaAcceptListItem'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /eula/{version_id}/view:
    get:
      tags:
        - EULA
      summary: Gets the text of a particular EULA version
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: version_id
          in: path
          description: |
            The EULA version ID (or `latest`)
          required: true
          schema:
            type: string
          example: latest
        - name: lang
          in: query
          description: The desired language of the specified EULA version
          schema:
            type: string
          example: en-US
      responses:
        200:
          description: HTML Text of the desired EULA version
          content:
            text/plain; charset=utf-8:
              schema:
                type: string
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/html:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/html:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions:
    post:
      operationId: CreateSubmission
      tags:
        - Submission
      summary: Create a new Submission
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmissionBase'
        required: true
      responses:
        201:
          description: Submission successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleSubmissionResponse'
          links:
            UploadSubmittedFileLink:
              operationId: UploadSubmittedFile
              parameters:
                id: '$response.body#/id'
            GetSubmiddionDetailsLink:
              operationId: GetSubmiddionDetails
              parameters:
                id: '$response.body#/id'
            DeleteSubmissionLink:
              operationId: DeleteSubmission
              parameters:
                id: '$response.body#/id'
            RecoverSubmissionLink:
              operationId: RecoverSubmission
              parameters:
                id: '$response.body#/id'
            GetSimilarityReportResultsLink:
              operationId: GetSimilarityReportResults
              parameters:
                id: '$response.body#/id'
            RequestSimilarityReportLink:
              operationId: RequestSimilarityReport
              parameters:
                id: '$response.body#/id'
            GetSimilarityReportUrlLink:
              operationId: GetSimilarityReportUrl
              parameters:
                id: '$response.body#/id'
            RequestSimilarityReportPdfLink:
              operationId: RequestSimilarityReportPdf
              parameters:
                id: '$response.body#/id'
            DownloadSimilarityReportPdfLink:
              operationId: DownloadSimilarityReportPdf
              parameters:
                id: '$response.body#/id'
            GetSimilarityReportPdfStatusLink:
              operationId: GetSimilarityReportPdfStatus
              parameters:
                id: '$response.body#/id'
            GetIndexStatusLink:
              operationId: GetIndexStatus
              parameters:
                id: '$response.body#/id'
            IndexSubmissionLink:
              operationId: IndexSubmission
              parameters:
                id: '$response.body#/id'
            SubmissionCompleteWebhookLink:
              operationId: SubmissionCompleteWebhook
              parameters:
                id: '$request.body#/id'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /submissions/{id}/original:
    put:
      operationId: UploadSubmittedFile
      tags:
        - Submission
      summary: Upload Submitted File
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
        - name: Content-Type
          in: header
          description: |
            *Must be 'binary/octet-stream'
          required: true
          schema:
            type: string
        - name: Content-Disposition
          in: header
          description: |
            *must include the "filename" parameter, e.g. `inline; filename="MyFile.docx"`. To support UTF-8 filenames, you must URL encode the header
          required: true
          schema:
            type: string
            example: inline; filename="MyFile.docx"
      requestBody:
        description: the user's submitted file
        content:
          binary/octet-stream:
            schema:
              type: object
              format: binary
        required: true
      responses:
        202:
          description: |
            Success message indicating successful PUT request for a submission upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
          links:
            SubmissionCompleteWebhookLink:
              operationId: SubmissionCompleteWebhook
              parameters:
                id: '$request.body#/id'
        400:
          description: Invalid submission file size, Submission file must be > than 0 MB and <= to 100 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionSizeError'
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: file
  /submissions/{id}:
    get:
      operationId: GetSubmiddionDetails
      tags:
        - Submission
      summary: Get Submission Details
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully retrieved Submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: DeleteSubmission
      tags:
        - Submission
      summary: Deletes a submission and associated similarity report.
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
        - name: hard
          in: query
          description: |
            Accepts true or false indicating either hard or soft delete. A soft delete removes the associated submission report/index and changes the saved submission state to DELETED. A hard deletion completely removes the submission information from Panda and TCA and removes the associated report/index, which can not be recovered.
          schema:
            type: string
            default: "false"
      responses:
        200:
          description: |
            Success message indicating successful Delete request for a submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        403:
          description: Not properly authenticated
          content: {}
        404:
          description: Submission not found for {id}
          content: {}
        409:
          description: Deletion error
          content: {}
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{id}/recover:
    put:
      operationId: RecoverSubmission
      tags:
        - Submission
      summary: Recover a soft deleted submission
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully recovered Submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleSubmissionResponse'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{id}/similarity:
    get:
      operationId: GetSimilarityReportResults
      tags:
        - Similarity
      summary: Get Similarity Report Results
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully retrieved Similarity info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarityMetadata'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: RequestSimilarityReport
      tags:
        - Similarity
      summary: Request Similarity Report generation
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarityPutRequest'
        required: true
      responses:
        202:
          description: |
            Success message indicating successful scheduling of Similarity Report generation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
          links:
            SimilarityCompleteWebhookLink:
              operationId: SimilarityCompleteWebhook
              parameters:
                id: '{request.body#/id}'
            SimilarityUpdatedWebhookLink:
              operationId: SimilarityUpdatedWebhook
              parameters:
                id: '{request.body#/id}'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /submissions/{id}/viewer-url:
    post:
      operationId: GetSimilarityReportUrl
      tags:
        - Similarity
      summary: Returns a URL to access Cloud Viewer
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarityViewerUrlSettings'
        required: true
      responses:
        200:
          description: |
            Success message indicating URL for launching similarity report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarityViewerUrlResponse'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /submissions/{id}/similarity/pdf:
    post:
      operationId: RequestSimilarityReportPdf
      tags:
        - Similarity
      summary: Request Pdf download and returns the Pdf Id
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSimilarityPDF'
        required: true
      responses:
        200:
          description: |
            Success message indicating ID for the PDF generation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestPdfResponse'
          links:
            DownloadSimilarityReportPdfLink:
              operationId: DownloadSimilarityReportPdf
              parameters:
                pdf_id: '$response.body#/id'
            GetSimilarityReportPdfStatusLink:
              operationId: GetSimilarityReportPdfStatus
              parameters:
                pdf_id: '$response.body#/id'
            PDFStatusWebhookLink:
              operationId: PDFStatusWebhook
              parameters:
                id: '$response.body#/id'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        404:
          description: Submission not found for {id}
          content: {}
        409:
          description: A Similarity Report is already generating for this submission
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{id}/similarity/pdf/{pdf_id}:
    get:
      operationId: DownloadSimilarityReportPdf
      tags:
        - Similarity
      summary: GET download pdf
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
        - name: pdf_id
          in: path
          description: |
            The Pdf ID (returned upon a successful POST to /submissions/{submission_id}/similarity/pdf)
          required: true
          schema:
            type: string
      responses:
        200:
          description: StreamingResponseBody, Pdf binary
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        202:
          description: |
            Status message indicating processing status for requested PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfStatusResponse'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        404:
          description: Submission not found for {id} or Pdf not found
          content: {}
        409:
          description: A Similarity Report is already generating for this submission or Failed to generate PDF
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{id}/similarity/pdf/{pdf_id}/status:
    get:
      operationId: GetSimilarityReportPdfStatus
      tags:
        - Similarity
      summary: GET pdf download status
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
        - name: pdf_id
          in: path
          description: |
            The Pdf ID (returned upon a successful POST to /submissions/{submission_id}/similarity/pdf)
          required: true
          schema:
            type: string
      responses:
        200:
          description: |
            Status message indicating processing status for requested PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfStatusResponse'
        202:
          description: |
            Status message indicating processing status for requested PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfStatusResponse'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        404:
          description: Submission not found for {id} or Pdf not found
          content: {}
        409:
          description: A Similarity Report is already generating for this submission or Failed to generate PDF
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{id}/index:
    get:
      operationId: GetIndexStatus
      tags:
        - Index
      summary: Return index state of submission
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Index state of submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexStateSettings'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Submission has not been completed yet
          content: {}
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: IndexSubmission
      tags:
        - Index
      summary: Index and return index state of submission
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          description: |
            The Submission ID (returned upon a successful POST to /submissions)
          required: true
          schema:
            type: string
        - name: asynchronous
          in: query
          description: asynchronous request
          required: false
          schema:
            type: boolean
      responses:
        200:
          description: Successfully indexed submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexStateSettings'
        400:
          description: Request is malformed or missing required data
          content: {}
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks:
    get:
      tags:
        - Webhook
      summary: List registered Webhook endpoints
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Webhook
      summary: Register a Webhook endpoint
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookWithSecret'
        required: true
      callbacks:
        SUBMISSION_COMPLETE:
          '{$request.body#/url}':
            post:
              operationId: SubmissionCompleteWebhook
              parameters:
                - $ref: '#/components/parameters/WebhookSignatureHeader'
                - $ref: '#/components/parameters/WebhookEventTypeHeader'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                        - $ref: '#/components/schemas/Submission'
                        - type: object
                          properties:
                            metadata:
                              type: object
                              properties:
                                custom:
                                  type: string
              responses:
                200:
                  description: success
        SIMILARITY_COMPLETE:
          '{$request.body#/url}':
            post:
              operationId: SimilarityCompleteWebhook
              parameters:
                - $ref: '#/components/parameters/WebhookSignatureHeader'
                - $ref: '#/components/parameters/WebhookEventTypeHeader'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                        - $ref: '#/components/schemas/SimilarityMetadata'
                        - type: object
                          properties:
                            metadata:
                              type: object
                              properties:
                                custom:
                                  type: string
              responses:
                200:
                  description: success
        SIMILARITY_UPDATED:
          '{$request.body#/url}':
            post:
              operationId: SimilarityUpdatedWebhook
              parameters:
                - $ref: '#/components/parameters/WebhookSignatureHeader'
                - $ref: '#/components/parameters/WebhookEventTypeHeader'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                        - $ref: '#/components/schemas/SimilarityMetadata'
                        - type: object
                          properties:
                            metadata:
                              type: object
                              properties:
                                custom:
                                  type: string
              responses:
                200:
                  description: success
        PDF_STATUS:
          '{$request.body#/url}':
            post:
              operationId: PDFStatusWebhook
              parameters:
                - $ref: '#/components/parameters/WebhookSignatureHeader'
                - $ref: '#/components/parameters/WebhookEventTypeHeader'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The requesting Pdf status
                          enum:
                            - SUCCESS
                            - PENDING
                            - FAILED
                        id:
                          type: string
                          description: the PDF ID
                        submission_id:
                          type: string
                          description: the associated submission ID
                        metadata:
                          type: object
                          properties:
                            custom:
                              type: string
              responses:
                200:
                  description: success
        GROUP_ATTACHMENT_COMPLETE:
          '{$request.body#/url}':
            post:
              operationId: GroupAttachmentCompleteWebhook
              parameters:
                - $ref: '#/components/parameters/WebhookSignatureHeader'
                - $ref: '#/components/parameters/WebhookEventTypeHeader'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/GroupAttachmentResponse'
              responses:
                200:
                  description: success
      responses:
        201:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
          links:
            GetWebhookLink:
              operationId: GetWebhook
              parameters:
                id: '$response.body#/id'
            DeleteWebhookLink:
              operationId: DeleteWebhook
              parameters:
                id: '$response.body#/id'
            UpdateWebhookLink:
              operationId: UpdateWebhook
              parameters:
                id: '$response.body#/id'
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /webhooks/{id}:
    get:
      operationId: GetWebhook
      tags:
        - Webhook
      summary: Get Webhook endpoint info
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: DeleteWebhook
      tags:
        - Webhook
      summary: Delete Webhook endpoint
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: Success
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: UpdateWebhook
      tags:
        - Webhook
      summary: Update Webhook endpoint info
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPathRequest'
        required: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /groups/{group_id}:
    get:
      operationId: GetGroup
      tags:
        - Groups
      summary: Get group, group context and group context owners info
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: group_id
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully get AggregateGroup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateGroup'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Groups
      summary: upsert group, group context and group context owners info
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: group_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregateGroup'
        required: true
      responses:
        200:
          description: Successfully upssert group, group context and group context owners
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateGroup'
          links:
            GetGroupLink:
              operationId: GetGroup
              parameters:
                group_id: '$response.body#/id'
            GetGroupAttachmentsLink:
              operationId: GetGroupAttachments
              parameters:
                group_id: '$response.body#/id'
            AddGroupAttachmentLink:
              operationId: AddGroupAttachment
              parameters:
                group_id: '$response.body#/id'
            UploadGroupAttachmentLink:
              operationId: UploadGroupAttachment
              parameters:
                group_id: '$response.body#/id'
            GetGroupAttachmentLink:
              operationId: GetGroupAttachment
              parameters:
                group_id: '$response.body#/id'
            DeleteGroupAttachmentLink:
              operationId: DeleteGroupAttachment
              parameters:
                group_id: '$response.body#/id'
            UpdateGroupAttachmentLink:
              operationId: UpdateGroupAttachment
              parameters:
                group_id: '$response.body#/id'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /groups/{group_id}/attachments:
    get:
      operationId: GetGroupAttachments
      tags:
        - Groups
      summary: Get all attachments
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: group_id
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully get attachments
          content:
            application/json:
              schema:
                type: object
                properties:
                  attachments:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupAttachmentResponse'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: AddGroupAttachment
      tags:
        - Groups
      summary: Add attachment to a group. will create a group if it does not exist.
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: group_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddGroupAttachmentRequest'
        required: true
      responses:
        201:
          description: Successfully add attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddGroupAttachmentResponse'
          links:
            UploadGroupAttachmentLink:
              operationId: UploadGroupAttachment
              parameters:
                attach_id: '$response.body#/id'
            GetGroupAttachmentLink:
              operationId: GetGroupAttachment
              parameters:
                attach_id: '$response.body#/id'
            DeleteGroupAttachmentLink:
              operationId: DeleteGroupAttachment
              parameters:
                attach_id: '$response.body#/id'
            UpdateGroupAttachmentLink:
              operationId: UpdateGroupAttachment
              parameters:
                attach_id: '$response.body#/id'
            GroupAttachmentCompleteWebhookLink:
              operationId: GroupAttachmentCompleteWebhook
              parameters:
                id: '$response.body#/id'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
  /groups/{group_id}/attachments/{attach_id}/original:
    put:
      operationId: UploadGroupAttachment
      tags:
        - Groups
      summary: Upload Submitted File
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: |
            The Group ID (required to already exist)
          required: true
          schema:
            type: string
        - name: attach_id
          in: path
          description: |
            The attachment ID (returned from a successful group attachment request)
          required: true
          schema:
            type: string
        - name: Content-Disposition
          in: header
          description: |
            *must include the "filename" parameter, e.g. `inline; filename="MyFile.docx"`
          required: true
          schema:
            type: string
            example: inline; filename="MyFile.docx"
      requestBody:
        description: the attachment file
        content:
          binary/octet-stream:
            schema:
              type: object
              format: binary
        required: true
      responses:
        202:
          description: |
            Success message indicating successful PUT request for a submission upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
          links:
            GroupAttachmentCompleteWebhookLink:
              operationId: GroupAttachmentCompleteWebhook
              parameters:
                id: 'request.body#/attach_id'
        400:
          description: Invalid submission file size, Submission file must be > than 0 MB and <= to 100 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionSizeError'
        403:
          description: Not properly authenticated
          content: {}
        429:
          description: |
            Too many requests have been made in a short amount of time, please wait for
            a bit a try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: file
  /groups/{group_id}/attachments/{attach_id}:
    get:
      operationId: GetGroupAttachment
      tags:
        - Groups
      summary: Get group attachment
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: group_id
          required: true
          schema:
            type: string
        - name: attach_id
          in: path
          description: |
            The attachment ID (returned from a successful group attachment request)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully get attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupAttachmentResponse'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: DeleteGroupAttachment
      tags:
        - Groups
      summary: Hard delete group attachment
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: group_id
          required: true
          schema:
            type: string
        - name: attach_id
          in: path
          description: |
            The attachment ID (returned from a successful group attachment request)
          required: true
          schema:
            type: string
      responses:
        204:
          description: Attachment successfully deleted
          content: {}
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: UpdateGroupAttachment
      tags:
        - Groups
      summary: Patch a group attachment
      parameters:
        - $ref: '#/components/parameters/IntegrationFamilyHeader'
        - $ref: '#/components/parameters/IntegrationVersionHeader'
        - name: group_id
          in: path
          description: group_id
          required: true
          schema:
            type: string
        - name: attach_id
          in: path
          description: |
            The attachment ID (returned from a successful group attachment request)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddGroupAttachmentRequest'
        required: true
      responses:
        200:
          description: Successfully get attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupAttachmentResponse'
        default:
          description: An Error Occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: data
components:
  schemas:
    SubmissionBase:
      type: object
      properties:
        id:
          description: Submission id, optional field
          format: uuid
        owner:
          maxLength: 132
          type: string
          description: ID of the owning user
        owner_default_permission_set:
          type: string
          description: Default viewer permission set, accepts INSTRUCTOR, LEARNER, EDITOR, USER, APPLICANT, ADMINISTRATOR, UNDEFINED
          enum:
            - INSTRUCTOR
            - LEARNER
            - EDITOR
            - USER
            - APPLICANT
            - ADMINISTRATOR
            - UNDEFINED
        title:
          maxLength: 500
          type: string
          description: the title of the submission
        submitter:
          maxLength: 132
          type: string
          description: (optional) ID of the submitting user, if different from the owning user
        submitter_default_permission_set:
          type: string
          description: Default submitter permission set, accepts INSTRUCTOR, LEARNER, EDITOR, USER, APPLICANT, ADMINISTRATOR, UNDEFINED
          enum:
            - INSTRUCTOR
            - LEARNER
            - EDITOR
            - USER
            - APPLICANT
            - ADMINISTRATOR
            - UNDEFINED
        eula:
          $ref: '#/components/schemas/Eula'
        metadata:
          type: object
          properties:
            submitter:
              $ref: '#/components/schemas/Users'
            owners:
              type: array
              items:
                $ref: '#/components/schemas/Users'
            group:
              $ref: '#/components/schemas/Group'
            group_context:
              $ref: '#/components/schemas/GroupContext'
            original_submitted_time:
              type: string
              description: Optional original submision date
              format: date-time
            custom:
              type: string
              description: custom metadata
              example: '{"Hello": "data"}'
          description: (optional) Submission metadata. If a group context is included, it must be associated to a group
        extract_text_only:
          type: boolean
          description: (optional) indicates if the submission should be treated as a text only submission. A text only submission cannot generate full reports or be viewed in the viewer, but can use the index only endpoint to be indexed
      description: |
        A Submission is the base object on which other services (such as similarity) are offered. In order to use other services a Submission must first be created and successfully process, then other service objects can be created.
    Group:
      type: object
      properties:
        id:
          type: string
          description: |
            (required)
        name:
          type: string
        type:
          type: string
          enum:
            - ASSIGNMENT
            - FOLDER
    AggregateGroup:
      type: object
      properties:
        id:
          type: string
          description: |
            (required)
        name:
          type: string
        type:
          type: string
          enum:
            - ASSIGNMENT
            - FOLDER
        group_context:
          $ref: '#/components/schemas/GroupContext'
        due_date:
          type: string
          description: due date for the group
          format: date
        report_generation:
          type: string
          enum:
            - IMMEDIATELY
            - IMMEDIATELY_AND_DUE_DATE
    GroupContext:
      type: object
      properties:
        id:
          type: string
          description: |
            (required)
        name:
          type: string
        owners:
          type: array
          items:
            $ref: '#/components/schemas/Users'
    Users:
      type: object
      properties:
        id:
          type: string
          description: |
            (required)
        family_name:
          type: string
        given_name:
          type: string
        email:
          type: string
          format: email
    EulaVersion:
      type: object
      properties:
        version:
          type: string
          description: |
            The unique name of the EULA Version
        valid_from:
          type: string
          description: |
            The starting date indicating when acceptence of this EULA is considered valid
          format: date-time
        valid_until:
          type: string
          nullable: true
          description: |
            The ending date indicating when acceptence of this EULA is no longer valid
          format: date-time
        url:
          type: string
          description: |
            The url where the corresponding EULA page can be found
        available_languages:
          type: array
          description: |
            The languages (instances) of this version. 21 language locales are currently supported.
          items:
            type: string
            enum:
              - ar-SA
              - cs-CZ
              - da-DK
              - de-DE
              - el-GR
              - en-US
              - es-MX
              - fi-FI
              - fr-FR
              - it-IT
              - ja-JP
              - ko-KR
              - nb-NO
              - nl-NL
              - pl-PL
              - pt-BR
              - ro-RO
              - ru-RU
              - sv-SE
              - tr-TR
              - vi-VN
              - zh-CN
              - zh-TW
    EulaAcceptRequest:
      type: object
      properties:
        user_id:
          type: string
          description: |
            The unique id of the user in the external system
        accepted_timestamp:
          type: string
          description: |
            The timestamp marking when the EULA was accepted
          format: date-time
        language:
          type: string
          description: |
            The language code for which language instance of the EULA version was accepted
        version:
          type: string
          description: |
            The unique name of the EULA Version
    FeaturesEnabled:
      type: object
      properties:
        similarity:
          $ref: '#/components/schemas/FeaturesSimilarity'
        tenant:
          $ref: '#/components/schemas/FeaturesTenant'
        product_name:
          type: string
        access_options:
          type: array
          items:
            type: string
            enum:
              - NATIVE
              - CORE_API
              - DRAFT_COACH
    EulaAcceptListItem:
      type: object
      properties:
        user_id:
          type: string
          description: |
            The unique id of the user in the external system
        accepted_timestamp:
          type: string
          description: |
            The timestamp marking when the EULA was accepted
          format: date-time
        language:
          type: string
          description: |
            The language code for which language instance of the EULA version was accepted
        version:
          type: string
          description: |
            The unique name of the EULA Version
    SimpleSubmissionResponse:
      allOf:
        - type: object
          properties:
            id:
              type: string
              description: the unique ID of the submission
            owner:
              type: string
              description: the owner of the submission
            title:
              type: string
              description: the title of the submission
            status:
              type: string
              description: the current status of the Submission
              enum:
                - CREATED
                - PROCESSING
                - COMPLETE
                - DELETED
                - ERROR
            created_time:
              type: string
              description: |
                RFC3339 timestamp of when this submission was initially created. This is the time at which the POST to /submissions was made.
              format: date-time
    Submission:
      allOf:
        - type: object
          properties:
            owner:
              type: string
              description: the owner of the submission
            title:
              type: string
              description: the title of the submission
            status:
              type: string
              description: the current status of the Submission
              enum:
                - CREATED
                - PROCESSING
                - COMPLETE
                - DELETED
                - ERROR
            id:
              type: string
              description: the unique ID of the submission
            content_type:
              type: string
              description: the content type of the submission
            page_count:
              type: integer
              description: the number of pages in the submission
            word_count:
              type: integer
              description: the number of words in the submission
            character_count:
              type: integer
              description: the number of characters in the submission
            error_code:
              type: string
              description: |
                an error code representing the type of error encountered (if applicable)
              enum:
                - UNSUPPORTED_FILETYPE
                - PROCESSING_ERROR
                - CANNOT_EXTRACT_TEXT
                - TOO_LITTLE_TEXT
                - TOO_MUCH_TEXT
                - TOO_MANY_PAGES
                - FILE_LOCKED
                - CORRUPT_FILE
            created_time:
              type: string
              description: |
                RFC3339 timestamp of when this submission was initially created. This is the time at which the POST to /submissions was made.
              format: date-time
            capabilities:
              type: array
              description: Set of capabilities available to the current submission
              items:
                type: string
                enum:
                  - INDEX
                  - SIMILARITY
                  - VIEWER
    SimilarityPutRequest:
      required:
        - generation_settings
      type: object
      properties:
        indexing_settings:
          $ref: '#/components/schemas/IndexingSettings'
        generation_settings:
          $ref: '#/components/schemas/SimilarityGenerationSettings'
        view_settings:
          $ref: '#/components/schemas/SimilarityViewSettings'
    SimilarityMetadata:
      allOf:
        - $ref: '#/components/schemas/SimilarityScoreData'
        - required:
            - status
            - submission_id
            - time_generated
            - time_requested
            - top_matches
            - top_source_largest_matched_word_count
          type: object
          properties:
            submission_id:
              type: string
            status:
              type: string
              description: possible values PENDING, COMPLETE
            time_generated:
              type: string
              description: Time the report finished generating.  If not set the report has not finished generating
            time_requested:
              type: string
              description: Time the report was requested
            top_matches:
              type: array
              description: Top matches
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Source name
                  percentage:
                    type: number
                    description: Match percentage
                  submission_id:
                    type: string
                    description: Matching submission id
                  source_type:
                    type: string
                    description: Matching submission source type (INTERNET, PUBLICATION, SUBMITTED_WORK)
                  matched_word_count_total:
                    type: number
                    description: number of matching words
                  submitted_date:
                    type: string
                    description: date match was submitted
                  institution_name:
                    type: string
                    description: intitution name for matched SUBMITTED_WORK types
            top_source_largest_matched_word_count:
              type: integer
              description: Largest individual matched word count, 0 if there isn't a match to this submission.
              format: int32
    SimilarityViewerUrlSettings:
      type: object
      properties:
        author_metadata_override:
          $ref: '#/components/schemas/AuthorMetadataOverride'
        viewer_user_id:
          type: string
          description: viewer's user ID
        locale:
          type: string
          description: two character locale language setting (e.g. 'en' or 'de') or full value
          enum:
            - ar-SA
            - cs-CZ
            - de-DE
            - el-GR
            - en-US
            - es-MX
            - fi-FI
            - fr-FR
            - it-IT
            - ja-JP
            - ko-KR
            - nl-NL
            - pl-PL
            - pt-BR
            - ro-RO
            - ru-RU
            - sv-SE
            - tr-TR
            - vi-VN
            - zh-CN
            - zh-TW
        viewer_default_permission_set:
          type: string
          description: Default viewer permission set, accepts INSTRUCTOR, LEARNER, EDITOR, USER, APPLICANT, ADMINISTRATOR, UNDEFINED
        viewer_permissions:
          $ref: '#/components/schemas/ViewerPermissions'
        eula:
          $ref: '#/components/schemas/Eula'
        sidebar:
          $ref: '#/components/schemas/Sidebar'
        similarity:
          $ref: '#/components/schemas/SimilaritySettings'
        annotations:
          $ref: '#/components/schemas/AnnotationsSettings'
    GenerateSimilarityPDF:
      type: object
      properties:
        locale:
          type: string
          description: two character locale language setting (e.g. 'en' or 'de') or full value
          enum:
            - ar-SA
            - cs-CZ
            - de-DE
            - el-GR
            - en-US
            - es-MX
            - fi-FI
            - fr-FR
            - it-IT
            - ja-JP
            - ko-KR
            - nl-NL
            - pl-PL
            - pt-BR
            - ro-RO
            - ru-RU
            - sv-SE
            - tr-TR
            - vi-VN
            - zh-CN
            - zh-TW
    AnnotationsSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Used to enable annotations

    SimilaritySettings:
      type: object
      properties:
        default_mode:
          type: string
          description: default similarity mode when viewing a report; set to either match_overview or all_sources
          enum:
            - match_overview
            - all_sources
        modes:
          type: object
          properties:
            match_overview:
              type: boolean
              description: Used to enable use of the match overview mode in the viewer
            all_sources:
              type: boolean
              description: Used to enable use of the all sources mode in the viewer
        view_settings:
          type: object
          properties:
            save_changes:
              type: boolean
              description: Used to enable save changes in the Viewer and trigger SIMILARITY_UPDATED webhook callback
    Sidebar:
      type: object
      properties:
        default_mode:
          type: string
          description: |
            The default mode shown in the sidebar panel. The selected mode must be enabled in the tenant's license, request parameter, as well as the viewer's permission. The default mode is similarity.
          enum:
            - similarity
            - flags
            - documentDetails
            - sections_exclusion
    ViewerPermissions:
      type: object
      properties:
        may_view_submission_full_source:
          type: boolean
          description: Optional individual permission which override the default permission set.
        may_view_match_submission_info:
          type: boolean
          description: Optional individual permission which override the default permission set.
        may_view_flags_panel:
          type: boolean
          description: Optional individual permission which override the default permission set
        may_view_document_details_panel:
          type: boolean
          description: Optional individual permission which override the default permission set
        may_view_sections_exclusion_panel:
          type: boolean
          description: Optional individual permission which override the default permission set
    SimilarityViewerUrlResponse:
      type: object
      properties:
        viewer_url:
          type: string
          description: URL to be used to access Cloud Viewer visualization of similarity report matches
          format: url
    RequestPdfResponse:
      type: object
      properties:
        id:
          type: string
          description: The Pdf ID
          format: uuid
    PdfStatusResponse:
      type: object
      properties:
        status:
          type: string
          description: The requesting Pdf status
          enum:
            - SUCCESS
            - PENDING
            - FAILED
    IndexStateSettings:
      type: object
      properties:
        is_indexed:
          type: boolean
          description: |
            If true, is_indexed displays the index state of submission.
    WebhookWithSecret:
      allOf:
        - required:
            - signing_secret
          type: object
          properties:
            signing_secret:
              type: string
              description: a sercret used to sign all callbacks for this webhook
              format: binary
        - $ref: '#/components/schemas/WebhookBase'
    Webhook:
      allOf:
        - required:
            - id
          type: object
          properties:
            id:
              type: string
              description: unique id of webhook
            created_time:
              type: string
              description: |
                RFC3339  timestamp of when this Webhook was initially created. This is the time at which the POST to /webhooks was made.
              format: date-time
        - $ref: '#/components/schemas/WebhookBase'
    WebhookPathRequest:
      required:
        - event_types
      type: object
      properties:
        description:
          type: string
          description: a human readable description of the webhook
        event_types:
          type: array
          description: an array of the types of callbacks that will be sent to this webhook
          items:
            type: string
            enum:
              - SUBMISSION_COMPLETE
              - SIMILARITY_COMPLETE
              - SIMILARITY_UPDATED
              - PDF_STATUS
              - GROUP_ATTACHMENT_COMPLETE
    AddGroupAttachmentRequest:
      type: object
      properties:
        title:
          maxLength: 500
          minLength: 1
          type: string
          description: Attachment title
          example: My Template Attachment
        template:
          type: boolean
          description: template
          default: false
      description: Request Object to add group attachment.
    AddGroupAttachmentResponse:
      type: object
      properties:
        id:
          type: string
          description: Attachment uuid
          example: 768f4633-d4c5-3ba0-8814-caaf421c8985
      description: Object returned for add group attachment.
    GroupAttachmentResponse:
      type: object
      properties:
        id:
          type: string
          description: uuid
          example: 768f4633-d4c5-3ba0-8814-caaf421c8985
        title:
          type: string
          description: title
          example: History
        status:
          type: string
          description: status
          enum:
            - CREATED
            - PROCESSING
            - COMPLETE
            - ERROR
            - DELETE
        template:
          type: boolean
          description: template
      description: Object returned for group attachment.
    Error:
      type: object
      properties:
        status:
          type: string
          description: an HTTP Response JobStatus Code
        message:
          type: string
          description: A message explaining what happened
      description: The generic object returned for errors. Updated for recent TCA changes.
    RateLimitError:
      allOf:
        - $ref: '#/components/schemas/Error'
    SubmissionSizeError:
      allOf:
        - $ref: '#/components/schemas/Error'
    SuccessMessage:
      type: object
      properties:
        message:
          type: string
          description: message indicating a successful PUT request
      description: Object returned for success messages.
    FeaturesSimilarity:
      type: object
      properties:
        viewer_modes:
          $ref: '#/components/schemas/FeaturesViewerModes'
        generation_settings:
          $ref: '#/components/schemas/FeaturesGenerationSettings'
        view_settings:
          $ref: '#/components/schemas/FeaturesSimilarityViewSettings'
    FeaturesTenant:
      type: object
      properties:
        require_eula:
          type: boolean
          description: a flag indicating whether this tenant requires EULA checks to use this API
    Eula:
      type: object
      properties:
        accepted_timestamp:
          type: string
          description: |
            The timestamp marking when the EULA was accepted
          format: date-time
        language:
          type: string
          description: |
            The language code for which language instance of the EULA version was accepted
          example: en-US
        version:
          type: string
          description: |
            The unique name of the EULA Version
          example: latest
      description: (optional) EULA acceptence information which either updates an existing acceptence or creates a new acceptence
    IndexingSettings:
      type: object
      properties:
        add_to_index:
          type: boolean
          description: If set, the submission will be added to all valid node groups for future matching
    SimilarityGenerationSettings:
      required:
        - search_repositories
      type: object
      properties:
        search_repositories:
          type: array
          description: List of repositories to search
          items:
            type: string
            enum:
              - INTERNET
              - PUBLICATION
              - SUBMITTED_WORK
              - PRIVATE
              - CROSSREF
              - CROSSREF_POSTED_CONTENT
        submission_auto_excludes:
          type: array
          description: List of submission IDs to exclude from report
          items:
            type: string
            format: uuid
            example: 0dacc0d5-2deb-4564-97f9-726d89b6617f
        auto_exclude_self_matching_scope:
          type: string
          description: self matching submissions to exclude from report
          enum:
            - ALL
            - GROUP
            - GROUP_CONTEXT
            - NONE
        priority:
          type: boolean
          description: Priority level of report generation
          example: false
    FeaturesSimilarityViewSettings:
      type: object
      properties:
        exclude_quotes:
          type: boolean
          description: |
            If set to true, text in quotes will not count as similar content
          example: true
        exclude_bibliography:
          type: boolean
          description: |
            If set to true, text in a bibliography section will not count as similar content
          example: true
        exclude_citations:
          type: boolean
          description: |
            If set to true, text in citations will not count as similar content
          example: true
        exclude_abstract:
          type: boolean
          description: |
            If set to true, text in the abstract section of the submission will not count as similar content
          example: true
        exclude_methods:
          type: boolean
          description: |
            If set to true, text in the method section of the submission will not count as similar content
          example: true
        exclude_small_matches:
          type: boolean
          description: |
            If set, similarity matches that match less than the specified amount of words will not count as similar content
          example: true
        exclude_internet:
          type: boolean
          description: |
            If set to true, text matched to the internet collection will not count as similar content
          example: true
        exclude_publications:
          type: boolean
          description: |
            If set to true, text matched to the publications collection will not count as similar content
          example: true
        exclude_crossref:
          type: boolean
          description: |
            If set to true, text matched to the Crossref collection will not count as similar content
          example: true
        exclude_crossref_posted_content:
          type: boolean
          description: |
            If set to true, text matched to the Crossref Posted Content collection will not count as similar content
          example: true
        exclude_submitted_works:
          type: boolean
          description: |
            If set to true, text matched to the submitted works collection will not count as similar content calculated as if submitted work was not part of the paper
          example: true
        exclude_custom_sections:
          type: boolean
          description: |
            If set to true, text matched to the custom sections defined in the admin settings will not count as similar content calculated as if section was not part of the paper
          example: true
        exclude_preprints:
          type: boolean
          description: |
            If set to true, it will exclude preprints. A preprint is a version of a scholarly or scientific paper that precedes formal peer review and publication in a peer-reviewed scholarly or scientific journal.
          example: true
    SimilarityViewSettings:
      type: object
      properties:
        exclude_quotes:
          type: boolean
          description: |
            If set to true, text in quotes will not count as similar content
          example: true
        exclude_bibliography:
          type: boolean
          description: |
            If set to true, text in a bibliography section will not count as similar content
          example: true
        exclude_citations:
          type: boolean
          description: |
            If set to true, text in citations will not count as similar content
          example: true
        exclude_abstract:
          type: boolean
          description: |
            If set to true, text in the abstract section of the submission will not count as similar content
          example: true
        exclude_methods:
          type: boolean
          description: |
            If set to true, text in the method section of the submission will not count as similar content
          example: true
        exclude_small_matches:
          type: integer
          description: |
            If set, similarity matches that match less than the specified amount of words will not count as similar content
          example: 4
        exclude_internet:
          type: boolean
          description: |
            If set to true, text matched to the internet collection will not count as similar content
          example: true
        exclude_publications:
          type: boolean
          description: |
            If set to true, text matched to the publications collection will not count as similar content
          example: true
        exclude_crossref:
          type: boolean
          description: |
            If set to true, text matched to the Crossref collection will not count as similar content
          example: true
        exclude_crossref_posted_content:
          type: boolean
          description: |
            If set to true, text matched to the Crossref Posted Content collection will not count as similar content
          example: true
        exclude_submitted_works:
          type: boolean
          description: |
            If set to true, text matched to the submitted works collection will not count as similar content calculated as if submitted work was not part of the paper
          example: true
        exclude_custom_sections:
          type: boolean
          description: |
            If set to true, text matched to the custom sections defined in the admin settings will not count as similar content calculated as if section was not part of the paper
          example: true
        exclude_preprints:
          type: boolean
          description: |
            If set to true, it will exclude preprints. A preprint is a version of a scholarly or scientific paper that precedes formal peer review and publication in a peer-reviewed scholarly or scientific journal.
          example: true
    SimilarityScoreData:
      required:
        - overall_match_percentage
      type: object
      properties:
        overall_match_percentage:
          type: integer
          description: Represents the percentage match against all sources
          format: int32
        internet_match_percentage:
          type: integer
          nullable: true
          description: Represents the percentage match against internet
          format: int32
        publication_match_percentage:
          type: integer
          nullable: true
          description: Represents the percentage match against all publications
          format: int32
        submitted_works_match_percentage:
          type: integer
          nullable: true
          description: Represents the percentage match against all submitted works
          format: int32
    AuthorMetadataOverride:
      type: object
      properties:
        given_name:
          type: string
          description: Given or first name of submission author
        family_name:
          type: string
          description: Family or last name of submission author
    WebhookBase:
      required:
        - event_types
        - url
      type: object
      properties:
        description:
          type: string
          description: a human readable description of the webhook
        url:
          type: string
          description: the URL to callback with events, this must be https unless (allow_insecure is true)
        allow_insecure:
          type: boolean
          description: if using an non https url, this must be set to true
        event_types:
          type: array
          description: an array of the types of callbacks that will be sent to this webhook
          items:
            type: string
            enum:
              - SUBMISSION_COMPLETE
              - SIMILARITY_COMPLETE
              - SIMILARITY_UPDATED
              - PDF_STATUS
              - GROUP_ATTACHMENT_COMPLETE
    FeaturesViewerModes:
      type: object
      properties:
        match_overview:
          type: boolean
        all_sources:
          type: boolean
    FeaturesGenerationSettings:
      type: object
      properties:
        search_repositories:
          type: array
          description: List of repositories to search
          items:
            type: string
            enum:
              - INTERNET
              - PUBLICATION
              - SUBMITTED_WORK
              - PRIVATE
              - CROSSREF
              - CROSSREF_POSTED_CONTENT
        submission_auto_excludes:
          type: boolean
  responses:
    ErrorResponse:
      description: An Error Occurred
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    GetPdfStatusResponse:
      description: |
        Status message indicating processing status for requested PDF
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/PdfStatusResponse'
    RateLimitErrorResponse:
      description: |
        Too many requests have been made in a short amount of time, please wait for
        a bit a try again.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/RateLimitError'
    RequestPdfResponse:
      description: |
        Success message indicating ID for the PDF generation request
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/RequestPdfResponse'
    SimilaritySuccessMessage:
      description: |
        Success message indicating successful scheduling of Similarity Report generation
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/SuccessMessage'
    SimilarityViewerUrlResponse:
      description: |
        Success message indicating URL for launching similarity report
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/SimilarityViewerUrlResponse'
    SubmissionDeleteSuccessMessage:
      description: |
        Success message indicating successful Delete request for a submission
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/SuccessMessage'
    SubmissionSizeErrorResponse:
      description: Invalid submission file size, Submission file must be > than 0 MB and <= to 100 MB
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/SubmissionSizeError'
    SubmissionSuccessMessage:
      description: |
        Success message indicating successful PUT request for a submission upload
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/SuccessMessage'
  parameters:
    IntegrationFamilyHeader:
      description: a human readable string representing the type of integration being used
      name: X-Turnitin-Integration-Name
      in: header
      example: myintegration
      required: true
      schema:
        type: string
    IntegrationVersionHeader:
      description: the version of the integration platform being used
      name: X-Turnitin-Integration-Version
      in: header
      example: v1.0.2
      required: true
      schema:
        type: string
    WebhookSignatureHeader:
      in: header
      name: X-Turnitin-Signature
      description: An HMAC256 signature of the request body, using the signing_secret supplied when registering the webhook
      required: true
      schema:
        type: string
    WebhookEventTypeHeader:
      in: header
      name: X-Turnitin-EventType
      description: The name of the event type for this request
      required: true
      schema:
        type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header