openapi: 3.2.0
info:
  title: AI Governance - AI Governance Entity Workflow Management API
  version: '1.0'
  contact:
    name: OneTrust Support
    url: https://my.onetrust.com/s/contactsupport
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: The AI Governance APIs are used to integrate external systems and streamline the flow of data with AI Governance in the OneTrust Platform.
servers:
- url: https://{hostname}
  variables:
    hostname:
      default: hostname
      description: The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com.
tags:
- name: Entity Workflow Management
  description: The Entity Workflow Management APIs are used to manage AI Governance entity workflows.
  externalDocs:
    description: OpenAPI 3.1.0 - Download Definition
    url: https://developer.onetrust.com/onetrust/openapi/ai-governance.json
paths:
  /api/ai-governance/v1/assignments/entities/{entityId}/types/{type}/stage:
    post:
      operationId: assignStageByName
      summary: Update Entity Workflow Stage
      description: 'Use this API to update the workflow stage for the specified entity record.


        > 🗒 Things to Know

        >

        > - This API only supports AI Governance entities (Models, Datasets, AI Systems, and AI Agents).

        > - AI Governance APIs will become available over the course of the Spring as customer tenants are upgraded to enhanced AI Governance services. No customer action is required and more detailed information will be published in upcoming release notes and product documentation.'
      tags:
      - Entity Workflow Management
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/ai-governance.json
      parameters:
      - name: entityId
        in: path
        description: Identifier of the entity
        required: true
        schema:
          description: Identifier of the entity
          type: string
          format: uuid
        example: f7114aef-b6b6-42d6-9249-56a467950aa7
      - name: type
        in: path
        description: Workflow Type
        required: true
        schema:
          description: Workflow type Name
          type: string
          format: uuid
        example: 3933259d-fc21-41e2-b511-18c11cedf938
      requestBody:
        required: true
        content:
          application/json:
            schema:
              example:
                nextStageName: Remediating
                parameters:
                  executeRule: true
              $ref: '#/components/schemas/WorkflowSpecificStageNavigationRequest'
      responses:
        '200':
          description: Successfully assigned the workflow stage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStageListInformation'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview)."
          headers:
            Retry-After:
              schema:
                description: The number of seconds after which requests will be allowed again.
                format: int32
            ot-period:
              schema:
                description: The unit of time for which the rate limit applies
                enum:
                - HOUR
                - MINUTE
            ot-ratelimit-event-id:
              schema:
                description: The unique identifier for the rate-limiting event.
                format: uuid
            ot-request-made:
              schema:
                description: The number of requests made within the specified period.
                format: int32
            ot-requests-allowed:
              schema:
                description: The number of requests allowed within the specified period.
                format: int32
        '500':
          description: Internal Server Error
      security:
      - OAUTH2:
        - AI_GOVERNANCE
        - AI_GOVERNANCE_WRITE
components:
  schemas:
    WorkflowSpecificStageNavigationRequest:
      type: object
      properties:
        nextStageName:
          description: Name of the next stage to navigate to
          type: string
          example: Investigation
        parameters:
          description: Additional parameters for workflow navigation customization
          additionalProperties:
            type: object
          example:
            skipValidation: true
            notifyUsers: false
          type: object
      example:
        nextStageName: Investigation
        parameters:
          notifyUsers: false
          priority: high
          reason: Critical security incident
          skipValidation: true
      required:
      - nextStageName
    WorkflowStageApproverInformation:
      type: object
      properties:
        id:
          description: Workflow Stage Approver Identifier
          type: string
          format: uuid
        workFlowStageId:
          description: Workflow Stage Id
          type: string
          format: uuid
        approverType:
          description: Workflow Stage Approver Type
          type: string
          enum:
          - SYSTEM_USER, USER_ATTRIBUTE
        approverUserId:
          description: Workflow Stage Approver User Id, User ID from Onetrust System
          type: string
          format: uuid
        referenceApproverUserSourceId:
          description: Reference identifier for approver' source. ie, fieldName from attribute Manager
          type: string
        referenceApproverUserSourceOwner:
          description: Reference Source Owner. ie, schemaname from attribute manager
          type: string
        approverUserGroupId:
          description: Workflow Stage Approver User Group Id, User Group ID from Onetrust System
          type: string
          format: uuid
        approverCategory:
          description: Field to indicate if the approver is for stage approval or exception
          type: string
        customFields:
          description: Custom fields
          type: object
          additionalProperties:
            type: object
      required:
      - approverType
      - id
      - workFlowStageId
    AdvanceStageActionInformation:
      type: object
      properties:
        id:
          description: Advance Stage Action Identifier
          type: string
          format: uuid
        actionType:
          description: Advance Stage Action Type
          type: string
          enum:
          - ATTRIBUTES, ATTACHMENT
        actionMetadata:
          description: Advance Stage Action metadata
          type: object
          additionalProperties:
            type: object
      required:
      - actionType
      - id
    StageExceptionInformation:
      type: object
      properties:
        stageExceptionApprovers:
          description: Workflow Stage Exception Approvers
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStageApproverInformation'
        exceptionGrantedTargetStageId:
          description: Target stage for exception approval
          type: string
          format: uuid
        workflowExceptionApprovalRequiredFromAll:
          description: Is exception required from all approvers
          type: boolean
    WorkflowStageListInformation:
      type: object
      properties:
        id:
          description: Workflow Stage Identifier
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          description: Workflow Stage Name
          type: string
          example: Investigation
        nameKey:
          description: Workflow Stage Name Key for translation purposes
          type: string
          example: workflow.stage.investigation
        description:
          description: Workflow Stage Description
          type: string
          example: Investigation stage for incident workflow
        descriptionKey:
          description: Workflow Stage Description Key for translation purposes
          type: string
          example: workflow.stage.investigation.description
        sequence:
          description: Workflow Stage Sequence number
          type: integer
          format: int32
          example: 2
          minimum: 1
        allowDeletion:
          description: Indicates if Workflow Stage can be deleted
          type: boolean
          example: true
          default: 'false'
        badgeColor:
          description: Workflow Stage Badge Color for UI purposes
          type: string
          example: blue
        approvalStage:
          description: Indicates if the stage is an approval stage
          type: boolean
          example: true
          default: 'false'
        exceptionStage:
          description: Indicates if the stage is an exception approval stage
          type: boolean
          example: false
          default: 'false'
        autoAdvanceOnApproval:
          description: Can Workflow Stage Auto-Advance on Approval?
          type: boolean
          example: true
          default: 'false'
        customFields:
          description: Custom fields
          type: object
          example:
            priority: high
            category: security
          additionalProperties:
            type: object
        stageApprovers:
          description: Workflow Stage Approvers
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStageApproverInformation'
        additionalFields:
          description: Additional fields associated with Workflow Stage
          type: object
          example:
            notificationEnabled: true
          additionalProperties:
            type: object
        advanceStageActionEnabled:
          description: Does Workflow Stage has advance stage action enabled?
          type: boolean
          example: true
          default: 'false'
        advanceStageActions:
          description: Workflow Stage Advance Actions
          type: array
          items:
            $ref: '#/components/schemas/AdvanceStageActionInformation'
        stageExceptionConfiguration:
          description: Workflow Stage Exception details
          $ref: '#/components/schemas/StageExceptionInformation'
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        name: Investigation
        nameKey: workflow.stage.investigation
        description: Investigation stage for incident workflow
        descriptionKey: workflow.stage.investigation.description
        sequence: 2
        allowDeletion: true
        badgeColor: blue
        approvalStage: true
        exceptionStage: false
        autoAdvanceOnApproval: true
        customFields:
          priority: high
          category: security
        stageApprovers:
        - id: abc-123
          name: Security Approver
        additionalFields:
          notificationEnabled: true
        advanceStageActionEnabled: true
        advanceStageActions:
        - id: def-456
          name: Approve
        stageExceptionConfiguration:
          enabled: true
          approverCount: 2
      required:
      - id
      - name
      - sequence
  securitySchemes:
    OAUTH2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{hostname}/api/access/v1/oauth/token
          scopes:
            AI_GOVERNANCE: Grants full permissions to manage AI Governance operations for external systems
            AI_GOVERNANCE_READ: Allows read-only access to AI Governance entities
            AI_GOVERNANCE_WRITE: Grants permissions to create and modify AI Governance entities
x-onetrust:
  spec-label: OpenAPI 3.1.0
x-readme:
  explorer-enabled: false
  proxy-enabled: false
  metrics-enabled: false