MINE Assessment API

openapi: 3.2.0
info:
  title: MineOS Aispm Assessment API
  version: v1.0
servers:
- url: https://api.portal.saymine.com/
  description: MineOS EU API Endpoint
- url: https://api.us.portal.saymine.com/
  description: MineOS US API Endpoint
security:
- Bearer: []
tags:
- name: Assessment
paths:
  /api/public-v1/assessment/List:
    get:
      tags:
      - Assessment
      summary: Retrieves a list of assessments based on the provided type and pagination parameters.
      parameters:
      - name: type
        in: query
        description: The type of assessments to retrieve (e.g. PIA, DPIA, TIA).
        schema:
          $ref: '#/components/schemas/PageType'
      - name: offset
        in: query
        description: The optional starting point for pagination. Defaults to 0.
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The optional maximum number of assessments to retrieve. Defaults to 100.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicAssessmentPageResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
  /api/public-v1/assessment/{id}:
    get:
      tags:
      - Assessment
      summary: Retrieves the details of a specific assessment based on its unique identifier.
      parameters:
      - name: id
        in: path
        description: The unique identifier of the assessment to retrieve.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicAssessmentPageResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
  /api/public-v1/assessment/{id}/collaborators:
    post:
      tags:
      - Assessment
      summary: Sends an invitation to collaborators for the specified assessment.
      parameters:
      - name: id
        in: path
        description: The unique identifier of the assessment for which collaborators are being invited.
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: The request containing details of the collaborators to invite.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CollaboratorInviteRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/CollaboratorInviteRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CollaboratorInviteRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CollaboratorInviteRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
  /api/public-v1/assessment/form-submission:
    post:
      tags:
      - Assessment
      summary: Adds a new Form submission content for a system.
      requestBody:
        description: The data for the form submission wrapped in a Mine.Portal.Module.Assessments.FormSubmission.Api.Public.Contracts.Requests.PublicFormSubmissionRequest object.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PublicFormSubmissionRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/PublicFormSubmissionRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PublicFormSubmissionRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PublicFormSubmissionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicFormSubmissionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
  /api/public-v1/assessment/{id}/form-submission:
    get:
      tags:
      - Assessment
      summary: Retrieves form submissions for a specific assessment based on its identifier.
      parameters:
      - name: id
        in: path
        description: The unique identifier of the assessment for which to retrieve form submissions.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicFormSubmissionResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
  /api/public-v1/assessment/from-template:
    post:
      tags:
      - Assessment
      summary: Creates a new assessment based on the provided template details.
      requestBody:
        description: The request containing the data required to create an assessment from a template.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreateFromTemplateRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFromTemplateRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateFromTemplateRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateFromTemplateRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAssessmentPageResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
  /api/public-v1/tprm/trigger:
    post:
      tags:
      - Assessment
      summary: Triggers a Third-Party Risk Management (TPRM) event based on the provided request details.
      requestBody:
        description: The request object containing the necessary data to trigger the TPRM event.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/TriggerTprmPublicRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerTprmPublicRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/TriggerTprmPublicRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/TriggerTprmPublicRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
  /api/public-v1/assessment/form-submission/{id}/attachment:
    post:
      tags:
      - Assessment
      summary: Uploads an attachment file for a specific form submission and triggers RAG indexing.
      parameters:
      - name: id
        in: path
        description: The unique identifier of the form submission.
        required: true
        schema:
          type: integer
          format: int32
      - name: filename
        in: query
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPublicResponse'
components:
  schemas:
    PublicQuestionResponse:
      type: object
      properties:
        id:
          type: integer
          description: The question's unique identifier within the assessment.
          format: int32
        layout:
          type:
          - string
          - 'null'
          description: Optional layout schema for the question, in JSON.
        type:
          $ref: '#/components/schemas/AssessmentQuestionTypeEnum'
        label:
          type:
          - string
          - 'null'
          description: The question's user-facing label.
        name:
          type:
          - string
          - 'null'
          description: The question's machine-readable name.
        value:
          description: 'The question''s stored value. Shape depends on Mine.Portal.Module.Assessments.Pages.Api.Public.Contracts.Responses.PublicQuestionResponse.Type: a string,

            a list of strings, an attachment object, etc. For reference-bearing types

            the value contains only ids; the resolved entities are returned on

            Mine.Portal.Module.Assessments.Pages.Api.Public.Contracts.Responses.PublicQuestionResponse.ReferencedObjects.'
        templateQuestionId:
          type:
          - string
          - 'null'
          description: The id of the template question this question was created from.
        formControlId:
          type:
          - string
          - 'null'
          description: The form control id used to bind this question in collaboration forms.
        referencedObjects:
          $ref: '#/components/schemas/PublicQuestionReferencedObjects'
      additionalProperties: false
      description: 'A single question within an assessment section. Reference-bearing questions

        (data sources, data subjects, data types, custom fields, etc.) include the

        resolved entity details in Mine.Portal.Module.Assessments.Pages.Api.Public.Contracts.Responses.PublicQuestionResponse.ReferencedObjects.'
    LockStatusResponse:
      type: object
      properties:
        isLocked:
          type: boolean
        lockedBy:
          type:
          - string
          - 'null'
        lockedAt:
          type:
          - string
          - 'null'
          format: date-time
        lockedUntil:
          type:
          - string
          - 'null'
          format: date-time
        collabState:
          $ref: '#/components/schemas/CollabState'
      additionalProperties: false
    PageType:
      enum:
      - Empty
      - AI
      - TIA
      - PIA
      - LIA
      - PA
      - AI_EU
      - ROI
      - Vendor
      - Privacy
      - DPIA
      - HIPAA
      - COPPA
      - NIST_CSF_Risk
      - Third_Party_DPIA
      - AI_Risk_Model_Developer_Focused
      - DORA_ICT_Third_Party_Criticality
      - DPIA_Simplified_ICO
      - DPIA_Standard_GDPR_V2
      - DPIA_CCPA
      - ADMT_CCPA
      type: string
    PublicDataTypeReference:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The data type id as stored on the question.
        name:
          type:
          - string
          - 'null'
          description: The data type's display name.
      additionalProperties: false
      description: A resolved reference to a data type used by data type questions.
    AssessmentQuestionTypeEnum:
      enum:
      - Default
      - BusinessPurpose
      - DataSources
      - Risks
      - ShortAnswer
      - TextBlock
      - Textarea
      - Dropdown
      - DatePicker
      - File
      - DataSubjects
      - BusinessUnit
      - DataRole
      - DataTypes
      - BusinessOwner
      - TransferMechanism
      - LegalBasis
      - PartiesWithAccess
      - DpiaNeeded
      - LinkedAssessment
      - DataFlow
      - DropdownCustomField
      - Text
      - TextCustomField
      type: string
    TriggerTprmPublicRequest:
      type: object
      properties:
        systemId:
          type:
          - string
          - 'null'
          description: 'The system identifier. Accepts either the system''s ExternalId (ShortGuid)

            or the system display name (for custom systems where the ExternalId is auto-generated).'
        requestedBusinessUnits:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Optional. The list of business units that are requested for the TPRM assessment.
        formSubmissionId:
          type:
          - integer
          - 'null'
          description: Optional. If provided, the TPRM assessment will be associated with this existing form submission.
          format: int32
      additionalProperties: false
    PublicSectionResponse:
      type: object
      properties:
        id:
          type: integer
          description: The section's unique identifier within the assessment.
          format: int32
        name:
          type:
          - string
          - 'null'
          description: The section's machine-readable name.
        label:
          type:
          - string
          - 'null'
          description: The section's user-facing label.
        layout:
          type:
          - string
          - 'null'
          description: Optional layout schema for the section, in JSON.
        templateSectionId:
          type:
          - string
          - 'null'
          description: The id of the template section this section was created from.
        formControlId:
          type:
          - string
          - 'null'
          description: The form control id used to bind this section in collaboration forms.
        questions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PublicQuestionResponse'
          description: The questions in this section, in the order defined by the template.
      additionalProperties: false
      description: 'A section of an assessment. Sections group related questions and follow the order

        defined by the assessment template.'
    CollaboratorInviteRequest:
      type: object
      properties:
        emailAddresses:
          type:
          - array
          - 'null'
          items:
            type: string
          description: A list of email addresses to which the collaborator invitation will be sent.
        requestor:
          type:
          - string
          - 'null'
          description: Optional. The identifier of the user initiating the collaborator invitation request.
        inviteMessage:
          type:
          - string
          - 'null'
          description: 'An optional custom message included in the invitation sent to collaborators.

            This message provides additional context or instructions for the invited users.'
      additionalProperties: false
      description: Represents a request to invite collaborators to an assessment.
    PublicFormSubmissionRequest:
      type: object
      properties:
        systemId:
          type:
          - string
          - 'null'
          description: Optional. The data source id to be associated with the form submission.
        content:
          type:
          - string
          - 'null'
          description: The content of the form submission, typically in JSON format.
        assessmentId:
          type:
          - integer
          - 'null'
          description: Optional. If provided, the form submission will be associated with this existing assessment.
          format: int32
        requestorEmails:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Optional. The email addresses of the users submitting the form.
      additionalProperties: false
    ErrorPublicResponse:
      type: object
      properties:
        internalErrorCode:
          $ref: '#/components/schemas/InternalErrorCode'
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
    PublicCustomFieldReference:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The custom field's unique id.
        name:
          type:
          - string
          - 'null'
          description: The custom field's user-facing label.
        inputType:
          $ref: '#/components/schemas/CustomFieldInputType'
        inputData:
          $ref: '#/components/schemas/InputConfig'
        description:
          type:
          - string
          - 'null'
          description: Optional description shown alongside the field.
      additionalProperties: false
      description: 'A resolved reference to a custom field used by dropdown and text custom-field

        questions. Mirrors the underlying custom-field definition so consumers can render

        the question (e.g. populate dropdown options, enforce input type) without an

        additional metadata request.'
    InviteStatusEnum:
      enum:
      - Invited
      - Revoked
      - Expired
      type: string
    PublicQuestionReferencedObjects:
      type: object
      properties:
        dataSources:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PublicSystemReference'
          description: 'Set for data source questions. Contains one entry per stored system id, with the

            system''s display name. Entries for ids that no longer exist keep the id and have

            a null name.'
        externalEntities:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PublicExternalEntityReference'
          description: 'Set for data subject, business unit, transfer mechanism, and legal basis questions.

            Contains the entity id, display name, and a flag indicating whether the entity is

            a built-in or company-defined value.'
        dataTypes:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PublicDataTypeReference'
          description: Set for data type questions. Contains the data type id and display name.
        customField:
          $ref: '#/components/schemas/PublicCustomFieldReference'
      additionalProperties: false
      description: 'Resolved entities referenced by a question. Only the field that matches the question''s

        type is populated; all other fields are null. The whole object is null when the question

        type doesn''t reference any entities, or when the question has no values to resolve.'
    PublicAssessmentPageResponse:
      type: object
      properties:
        id:
          type: integer
          description: The assessment's unique numeric identifier.
          format: int32
        name:
          type:
          - string
          - 'null'
          description: The assessment's user-facing name.
        ownerId:
          type:
          - string
          - 'null'
          description: The Employee ID of the assessment's owner. Null when the assessment is unassigned.
        createdDate:
          type: string
          description: The UTC timestamp at which the assessment was created.
          format: date-time
        updatedDate:
          type: string
          description: The UTC timestamp at which the assessment was last updated.
          format: date-time
        createdBy:
          type:
          - string
          - 'null'
          description: The id of the user who created the assessment.
        updatedBy:
          type:
          - string
          - 'null'
          description: The id of the user who last updated the assessment.
        type:
          $ref: '#/components/schemas/PageType'
        state:
          $ref: '#/components/schemas/State'
        collabState:
          $ref: '#/components/schemas/CollabState'
        templatePageId:
          type:
          - integer
          - 'null'
          description: The id of the template this assessment was created from.
          format: int32
        lastApprovedAt:
          type:
          - string
          - 'null'
          description: The UTC timestamp at which the assessment was last approved. Null if never approved.
          format: date-time
        isVendorSpecific:
          type: boolean
          description: True when the assessment is bound to a specific data source / vendor.
        sections:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PublicSectionResponse'
          description: Sections of the assessment, each containing the assessment's questions.
        tags:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PublicTagResponse'
          description: Tags attached to the assessment.
        collabInvites:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PublicCollabInviteResponse'
          description: Collaboration invites issued for the assessment.
        collabLockStatus:
          $ref: '#/components/schemas/LockStatusResponse'
        formSubmissions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AssessmentFormSubmission'
          description: Form submissions attached to the assessment.
        logic:
          type:
          - string
          - 'null'
          description: The assessment's logic schema, in JSON.
        layout:
          type:
          - string
          - 'null'
          description: The assessment's layout schema, in JSON.
        reviewDate:
          type:
          - string
          - 'null'
          description: The UTC timestamp scheduled for the next review of the assessment.
          format: date-time
        stateUpdatedAt:
          type:
          - string
          - 'null'
          description: The UTC timestamp at which the assessment's state was last updated.
          format: date-time
        vendorSpecificId:
          type:
          - string
          - 'null'
          description: 'The id of the data source (system) this assessment is bound to, when the assessment

            is data-source specific. Null otherwise.'
        dataSourceSpecific:
          type: boolean
          description: True when this assessment applies to a specific data source.
      additionalProperties: false
      description: 'An assessment returned by the public assessment endpoints. Contains the assessment''s

        metadata, its sections and questions, and resolved details for any entities the

        questions reference.'
    InputConfig:
      type: object
      properties:
        inputOptions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/InputOptions'
        useMultipleOptions:
          type: boolean
        useColors:
          type: boolean
      additionalProperties: false
    PublicTagResponse:
      type: object
      properties:
        id:
          type: integer
          description: The tag's unique numeric identifier.
          format: int32
        name:
          type:
          - string
          - 'null'
          description: The tag's user-facing name.
        description:
          type:
          - string
          - 'null'
          description: Optional description for the tag.
        type:
          type:
          - string
          - 'null'
          description: The tag's category (e.g. risk, framework).
        isDefault:
          type: boolean
          description: True when this tag is a built-in default; false when it was defined by the company.
      additionalProperties: false
      description: A tag attached to an assessment.
    CustomFieldInputType:
      enum:
      - Text
      - Select
      type: string
    State:
      enum:
      - Draft
      - Completed
      - Reject
      - InProgress
      type: string
    AssessmentFormSubmission:
      type: object
      properties:
        id:
          type: integer
          format: int32
        content:
          type:
          - string
          - 'null'
        systemId:
          type:
          - string
          - 'null'
        assessmentPageId:
          type:
          - integer
          - 'null'
          format: int32
      additionalProperties: false
    PublicSystemReference:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The system's unique id.
        name:
          type:
          - string
          - 'null'
          description: 'The system''s display name. Null when the id no longer resolves to an active

            system in the company''s inventory.'
      additionalProperties: false
      description: A resolved reference to a system (data source). Returned for data source questions.
    CollabState:
      enum:
      - None
      - Shared
      - Submitted
      type: string
    InternalErrorCode:
      enum:
      - GeneralError
      - NotFound
      - AlreadyExists
      - InvalidArgument
      type: string
    PublicExternalEntityReference:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The entity id as stored on the question.
        name:
          type:
          - string
          - 'null'
          description: The entity's display name.
        isDefault:
          type: boolean
          description: 'True when the entity is a built-in value provided by the platform; false when

            the entity is a company-defined custom value.'
      additionalProperties: false
      description: 'A resolved reference to an entity used by data subject, business unit,

        transfer mechanism, and legal basis questions.'
    PublicCollabInviteResponse:
      type: object
      properties:
        email:
          type:
          - string
          - 'null'
          description: The email address the invitation was sent to.
        status:
          $ref: '#/components/schemas/InviteStatusEnum'
        revoker:
          type:
          - string
          - 'null'
          description: The id of the user who revoked the invitation, if it was revoked.
        isDone:
          type: boolean
          description: True when the invited collaborator has marked their work as done.
        inviter:
          type:
          - string
          - 'null'
          description: The id of the user who issued the invitation.
        inviterEmail:
          type:
          - string
          - 'null'
          description: The email address of the user who issued the invitation.
        invitedAt:
          type:
          - string
          - 'null'
          description: The UTC timestamp at which the invitation was issued.
          format: date-time
        revokedAt:
          type:
          - string
          - 'null'
          description: The UTC timestamp at which the invitation was revoked, if it was revoked.
          format: date-time
      additionalProperties: false
      description: A collaboration invitation issued for an assessment.
    PublicFormSubmissionResponse:
      type: object
      properties:
        id:
          type: integer
          format: int32
        formSubmissionId:
          type: integer
          description: Duplicate of Id property, make FE use Id property instead and remove afterwards
          format: int32
          deprecated: true
        content:
          type:
          - string
          - 'null'
        requestorEmails:
          type:
          - array
          - 'null'
          items:
            type: string
      additionalProperties: false
    InputOptions:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        color:
          type:
          - string
          - 'null'
      additionalProperties: false
    CreateFromTemplateRequest:
      required:
      - name
      type: object
      properties:
        templateId:
          type: integer
          description: The Id of the template to create the new assessment from.
          format: int32
        name:
          minLength: 1
          type: string
          description: The name of the new assessment.
        systemId:
          type:
          - string
          - 'null'
          description: For a Vendor specific template, the systemId is required.
        owner:
          type:
          - string
          - 'null'
          description: The Employee ID of the assessment's owner.
        formSubmissionId:
          type:
          - integer
          - 'null'
          description: The ID of the form submission that this assessment is associated with.
          format: int32
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: apiKey
      description: "Authorization header using the Bearer sc

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mine/refs/heads/main/openapi/mine-assessment-api-openapi.yml