> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Entity Workflow Stage

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. 

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Governance - AI Governance",
    "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"
      }
    }
  ],
  "x-onetrust": {
    "spec-label": "OpenAPI 3.1.0"
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "metrics-enabled": false
  },
  "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.\n\n> 🗒 Things to Know\n> \n> - This API only supports AI Governance entities (Models, Datasets, AI Systems, and AI Agents).\n> - 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"
        ]
      },
      "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"
          }
        }
      },
      "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"
        ]
      },
      "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"
            }
          }
        }
      }
    }
  }
}
```