openapi: 3.0.0
paths:
  /organization:
    post:
      operationId: OrganizationController_createOrganization
      summary: Create Organization
      description: Creates an organization. User must be a Platform Admin
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrganizationResponseDto'
        '400':
          description: Organization field validation error or permission error
        '500':
          description: Organization creation unkown error
      tags:
        - Organization
    get:
      operationId: OrganizationController_getAllOrganizations
      summary: All Organizations
      description: Get all organizations. User must me platform admin
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReturnOrganizationDto'
        '400':
          description: Permission Error
      tags:
        - Organization
  /organization/{_id}:
    put:
      operationId: OrganizationController_updateOrganization
      summary: Update Organization metadata
      description: >-
        Update organization's name and description. User must be a Platform
        Admin
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnOrganizationDto'
        '400':
          description: Organization name, description validation error or permission error
      tags:
        - Organization
    get:
      operationId: OrganizationController_getOrganization
      summary: Get Organization
      description: >-
        Get organization. User must have GetOrganization permission on the
        organization
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to get details of
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnOrganizationDto'
        '400':
          description: Permission Error
      tags:
        - Organization
  /organization/{_id}/make-default:
    post:
      operationId: OrganizationController_makeOrgDefault
      summary: Mark as Default
      description: >-
        Keep this as the default organization of the platform. User must me
        platform admin
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to mark as default
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnOrganizationDto'
        '400':
          description: Permission Error
      tags:
        - Organization
  /organization/{_id}/permissions:
    patch:
      operationId: OrganizationController_updateOrgPermissions
      summary: Update Org Permissions
      description: >-
        Update Organization organization. User must have UpdateOrganization
        permission on the organization
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to update permissions of
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrgPermissionsDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnOrganizationDto'
        '400':
          description: Permission Error
      tags:
        - Organization
  /organization/{_id}/users:
    get:
      operationId: OrganizationController_getOrganizationUsers
      summary: Organization Users
      description: >-
        Get Organization Users. User must have GetOrganization permission on the
        organization
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to get users of
          schema:
            type: string
      responses:
        '200':
          description: ''
        '400':
          description: Permission Error
      tags:
        - Organization Users
  /organization/{_id}/users/{userId}:
    post:
      operationId: OrganizationController_addUserToOrganization
      summary: Add User
      description: >-
        Add user to the organization with the permissions defined. User must
        have AddUserToOrganization permission on the organization
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to add user to
          schema:
            type: string
        - name: userId
          required: true
          in: path
          description: User to add
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUserToOrganizationDto'
      responses:
        '200':
          description: ''
        '400':
          description: Permission Error
        '404':
          description: Org does not exist OR user does not exist OR
      tags:
        - Organization Users
    delete:
      operationId: OrganizationController_removeUserFromOrganization
      summary: Remove User
      description: >-
        Remove user from the organization. Calling user must have
        RemoveUserFromOrganization permission on the organization
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to remove user from
          schema:
            type: string
        - name: userId
          required: true
          in: path
          description: User to remove
          schema:
            type: string
      responses:
        '200':
          description: ''
        '400':
          description: Permission Error
        '404':
          description: Org does not exist OR user does not exist OR
      tags:
        - Organization Users
  /organization/{_id}/users/{userId}/permissions:
    patch:
      operationId: OrganizationController_updateUserPermissions
      summary: Update user permission
      description: >-
        Update permission of the user in the organization. Calling user must
        have UpdateOrganizationUserPermissions permission on the organization
      parameters:
        - name: _id
          required: true
          in: path
          description: Organization to update permissions of user in
          schema:
            type: string
        - name: userId
          required: true
          in: path
          description: User to update permissions of
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserPermissionsDto'
      responses:
        '200':
          description: ''
        '400':
          description: Permission Error
        '404':
          description: Org does not exist OR user does not exist OR
      tags:
        - Organization Users
  /moderation/analyze:
    post:
      operationId: ModerationController_analyzeText
      summary: Apply policies on messages
      parameters:
        - name: X-Num-Tokens
          in: header
          description: Number of tokens analyzed by policies
          schema:
            type: string
        - name: Warning
          in: header
          description: Warning displayed about tokens being not analyzed due to length
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnAnalyzeDto'
        '500':
          description: Error occured
      tags:
        - DynamoGuard Analyze
  /moderation/model/{modelId}/logs:
    get:
      operationId: ModerationController_getLogs
      summary: Get Logs
      description: >-
        Retrieve logs from chat and analyze interactions. Narrow search down by
        using the query filters.
      parameters:
        - name: modelId
          required: true
          in: path
          schema:
            type: string
        - name: startTime
          required: false
          in: query
          description: The start time (in UTC seconds) to filter by
          schema:
            type: number
        - name: endTime
          required: false
          in: query
          description: The end time (in UTC seconds) to filter by
          schema:
            type: number
        - name: pageNum
          required: false
          in: query
          description: The page number
          schema:
            default: 1
            type: number
        - name: perPage
          required: false
          in: query
          description: The number of results per page
          schema:
            default: 50
            type: number
        - name: sortDir
          required: false
          in: query
          description: The direction to sort results by.
          schema:
            default: desc
            enum:
              - asc
              - desc
            type: string
        - name: policyId
          required: false
          in: query
          description: The policy id to filter by
          schema:
            type: string
        - name: policyType
          required: false
          in: query
          description: The policy type to filter by
          schema:
            enum:
              - PII
              - TOXICITY
              - ALIGNMENT
              - HALLUCINATION
              - RAG_HALLUCINATION
            type: string
        - name: textType
          required: false
          in: query
          description: The text type to filter by
          schema:
            enum:
              - MODEL_INPUT
              - MODEL_RESPONSE
            type: string
        - name: action
          required: false
          in: query
          description: The policy action to filter by
          schema:
            enum:
              - BLOCK
              - WARN
              - REDACT
              - SANITIZE
              - NONE
            type: string
        - name: clientId
          required: false
          in: query
          description: The client id to filter by
          schema:
            type: string
        - name: userId
          required: false
          in: query
          description: The user id to filter by
          schema:
            type: string
        - name: metadata
          required: false
          in: query
          description: User-defined log metadata to filter by. Should be a json string
          example: >-
            {origin: {platform: "chatgpt.com", browser: "Chrome"}, version:
            "3.16"}
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullReturnLogDto'
      tags:
        - DynamoGuard Logs
  /moderation/model/{modelId}/logs/count:
    get:
      operationId: ModerationController_getLogsCount
      summary: Get Count of Logs
      description: >-
        Retrieve number of log entries from chat and analyze interactions.
        Narrow search down by using the query filters.
      parameters:
        - name: modelId
          required: true
          in: path
          schema:
            type: string
        - name: startTime
          required: false
          in: query
          description: The start time (in UTC seconds) to filter by
          schema:
            type: number
        - name: endTime
          required: false
          in: query
          description: The end time (in UTC seconds) to filter by
          schema:
            type: number
        - name: policyId
          required: false
          in: query
          description: The policy id to filter by
          schema:
            type: string
        - name: policyType
          required: false
          in: query
          description: The policy type to filter by
          schema:
            enum:
              - PII
              - TOXICITY
              - ALIGNMENT
              - HALLUCINATION
              - RAG_HALLUCINATION
            type: string
        - name: textType
          required: false
          in: query
          description: The text type to filter by
          schema:
            enum:
              - MODEL_INPUT
              - MODEL_RESPONSE
            type: string
        - name: action
          required: false
          in: query
          description: The policy action to filter by
          schema:
            enum:
              - BLOCK
              - WARN
              - REDACT
              - SANITIZE
              - NONE
            type: string
        - name: clientId
          required: false
          in: query
          description: The client id to filter by
          schema:
            type: string
        - name: userId
          required: false
          in: query
          description: The user id to filter by
          schema:
            type: string
        - name: metadata
          required: false
          in: query
          description: User-defined log metadata to filter by. Should be a json string
          example: >-
            {origin: {platform: "chatgpt.com", browser: "Chrome"}, version:
            "3.16"}
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: number
      tags:
        - DynamoGuard Logs
  /moderation/model/{modelId}/stats:
    get:
      operationId: ModerationController_getStats
      summary: Get stats
      description: >-
        Retrieve dashboard metrics. Narrow search down by using the query
        filters. At least one of modelId, clientId, or userId must be specified.
      parameters:
        - name: modelId
          required: true
          in: path
          schema:
            type: string
        - name: startTime
          required: false
          in: query
          description: The start time to filter by
          schema:
            type: number
        - name: endTime
          required: false
          in: query
          description: The end time to filter by
          schema:
            type: number
        - name: numDataPoints
          required: false
          in: query
          description: >-
            Number of data points to discretize time period. Must be greater
            than 1.
          schema:
            default: 2
            type: number
        - name: clientId
          required: false
          in: query
          description: The client id to filter by
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnStatsDto'
      tags:
        - DynamoGuard Stats
  /moderation/model/{modelId}/chat/{session_id}:
    post:
      operationId: ModerationController_chat
      summary: Guardrailed Chat
      description: >-
        Apply policies to messages and send non-violating prompts to LLM. Routes
        messages to the LLM behind modelId. Blocks/modifies prompt/response as
        policies dictate
      parameters:
        - name: modelId
          required: true
          in: path
          schema:
            type: string
        - name: session_id
          required: true
          in: path
          description: Session id to link chat messages to
          schema:
            type: string
        - name: X-Num-Tokens
          in: header
          description: Number of tokens analyzed by policies
          schema:
            type: string
        - name: Warning
          in: header
          description: Warning displayed about tokens being not analyzed due to length
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullReturnChatDto'
      tags:
        - DynamoGuard Chat
  /moderation/model/{id}/policies:
    put:
      operationId: ModerationController_updateModelPolicies
      summary: Update policies applied to a model
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateModelPoliciesDto'
      responses:
        '200':
          description: ''
      tags:
        - DynamoGuard Policy
  /moderation/policy:
    post:
      operationId: PolicyController_createPolicy
      summary: Create policy
      description: |-
        Creates a policy on DynamoGuard. 
                    Each policy uses methodParams as arguments for the underlying policy and 
                    decisionParams to determine the action to take based on the policy result.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePolicyDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnPolicyDto'
        '400':
          description: Either a rate limit was hit or policy failed validation
        '500':
          description: Policy fields failed validation
      tags:
        - DynamoGuard Policy
    get:
      operationId: PolicyController_getAllPolicies
      summary: Get all policies
      description: >-
        Retrieves all policies a user made. If modelId is specified, attaches
        policy statuses as well
      parameters:
        - name: policyType
          required: false
          in: query
          description: Policy type to filter on
          schema:
            enum:
              - PII
              - TOXICITY
              - ALIGNMENT
              - HALLUCINATION
              - RAG_HALLUCINATION
            type: string
        - name: modelId
          required: false
          in: query
          description: If specified, attaches policy status in relation to the modelId
          schema:
            type: string
        - name: expand
          required: false
          in: query
          description: 'If true, attaches dataset info. Only available for content policies '
          schema:
            type: boolean
        - name: attachModels
          required: false
          in: query
          description: If specified, attaches models policy is applied to
          schema:
            type: boolean
        - name: page
          required: true
          in: query
          schema:
            type: number
        - name: limit
          required: true
          in: query
          schema:
            type: number
        - name: includeAllowedScopes
          required: true
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllAugmentedReturnPoliciesDto'
      tags:
        - DynamoGuard Policy
  /moderation/policy/{id}:
    put:
      operationId: PolicyController_updatePolicy
      summary: Update policy
      description: Same description as policy creation
      parameters:
        - name: id
          required: true
          in: path
          description: Policy id to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePolicyDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnPolicyDto'
        '400':
          description: Policy failed validation
        '500':
          description: Policy fields failed validation
      tags:
        - DynamoGuard Policy
    get:
      operationId: PolicyController_getPolicy
      summary: Get policy
      description: Use query params to add additional information
      parameters:
        - name: id
          required: true
          in: path
          description: Policy id to retrieve
          schema:
            type: string
        - name: expand
          required: false
          in: query
          description: 'If true, attaches dataset info. Only available for content policies '
          schema:
            type: boolean
        - name: modelId
          required: false
          in: query
          description: >-
            If specified, attaches policy status in reference to the given
            model. Also filters policy stats.
          schema:
            type: string
        - name: promptId
          required: false
          in: query
          description: If specified, attaches feedback for the prompt
          schema:
            type: string
        - name: attachModels
          required: false
          in: query
          description: If specified, attaches models policy is applied to
          schema:
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AugmentedReturnPolicyDto'
      tags:
        - DynamoGuard Policy
    delete:
      operationId: PolicyController_deletePolicy
      summary: Delete policy
      parameters:
        - name: id
          required: true
          in: path
          description: Policy id to delete
          schema:
            type: string
      responses:
        '200':
          description: ''
      tags:
        - DynamoGuard Policy
  /moderation/policy/{id}/models:
    put:
      operationId: PolicyController_updatePolicyModels
      summary: Add/remove policy to/from models
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePolicyModelsDto'
      responses:
        '200':
          description: ''
      tags:
        - DynamoGuard Policy
  /health:
    get:
      operationId: HealthController_health
      summary: API Health Endpoint
      description: To check if the api is healthy
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Health
  /ml-model:
    post:
      operationId: ModelController_createModel
      summary: Create Remote Model
      description: >-
        Creates a remote model configuration. User must have CreateModel
        permission
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnModelDto'
        '400':
          description: Model validation error or permission error
        '500':
          description: Model creation unknown error
      tags:
        - Models
info:
  title: DynamoFL API
  description: ''
  version: 1.0.0
  contact: {}
tags: []
servers: []
components:
  schemas:
    CreateOrganizationDto:
      type: object
      properties:
        name:
          type: string
          description: Organization name. The names of the organization must be unique
        description:
          type: string
          description: Organization description
        isDefault:
          type: boolean
          description: Whether the organization is the default organization of the platform
      required:
        - name
        - description
    OrganizationCollaborator:
      type: object
      properties:
        userId:
          type: string
          description: User id of the collaborator
        permissions:
          type: string
          description: >-
            Permissions to assign to the collaborator. Must be of
            OrganizationPermission enum
          enum:
            - CreateOrganization
            - GetOrganization
            - GetAllOrganizations
            - UpdateOrganization
            - DeleteOrganization
            - MakeOrganizationDefault
            - AddUserToOrganization
            - RemoveUserFromOrganization
            - UpdateOrganizationUserPermissions
      required:
        - userId
        - permissions
    ReturnOrganizationDto:
      type: object
      properties:
        name:
          type: string
          description: Organization name. The names of the organization must be unique
        description:
          type: string
          description: Organization description
        isDefault:
          type: boolean
          description: Whether the organization is the default organization of the platform
        id:
          type: string
          description: Id of the organization
        created_at:
          format: date-time
          type: string
          description: Creation time of the organization
        publicLevelPermissions:
          type: string
          description: >-
            Public level permissions on org for all the users in the org. Must
            be of OrganizationPermission enum
          enum:
            - CreateOrganization
            - GetOrganization
            - GetAllOrganizations
            - UpdateOrganization
            - DeleteOrganization
            - MakeOrganizationDefault
            - AddUserToOrganization
            - RemoveUserFromOrganization
            - UpdateOrganizationUserPermissions
        collaborators:
          description: List of collaborators with the permissions to the organization
          type: array
          items:
            $ref: '#/components/schemas/OrganizationCollaborator'
      required:
        - name
        - description
        - id
        - created_at
        - publicLevelPermissions
        - collaborators
    CreateOrganizationResponseDto:
      type: object
      properties:
        admin:
          type: object
          description: Newly created admin account for the organization
        organization:
          description: Newly created organization
          allOf:
            - $ref: '#/components/schemas/ReturnOrganizationDto'
      required:
        - admin
        - organization
    UpdateOrganizationDto:
      type: object
      properties:
        name:
          type: string
          description: New name of the organization
        description:
          type: string
          description: New description of the organization
    UpdateOrgPermissionsDto:
      type: object
      properties:
        publicLevelPermissions:
          type: string
          description: >-
            Public level permissions on org for all the users in the org. Must
            be of OrganizationPermission enum
          enum:
            - CreateOrganization
            - GetOrganization
            - GetAllOrganizations
            - UpdateOrganization
            - DeleteOrganization
            - MakeOrganizationDefault
            - AddUserToOrganization
            - RemoveUserFromOrganization
            - UpdateOrganizationUserPermissions
        collaborators:
          description: List of collaborators with the permissions to the organization
          type: array
          items:
            $ref: '#/components/schemas/OrganizationCollaborator'
      required:
        - publicLevelPermissions
        - collaborators
    AddUserToOrganizationDto:
      type: object
      properties:
        permissions:
          description: List of permissions to assign to the user
          type: array
          items:
            type: string
      required:
        - permissions
    UpdateUserPermissionsDto:
      type: object
      properties:
        permissions:
          description: List of permissions to assign to the user
          type: array
          items:
            type: string
      required:
        - permissions
    AnalyzeMessage:
      type: object
      properties:
        role:
          type: string
          description: Role
          enum: &ref_1
            - user
            - assistant
            - system
        content:
          type: string
          description: Text to send
        ragContext:
          type: string
          description: >-
            Context retrieved from RAG. Currently only used for analyze
            endpoint, not chat.
      required:
        - role
        - content
    AnalyzeDto:
      type: object
      properties:
        messages:
          description: OpenAI style messages with optional RAG context to analyze
          type: array
          items:
            $ref: '#/components/schemas/AnalyzeMessage'
        textType:
          type: string
          description: Whether last message is a prompt or response
          enum:
            - MODEL_INPUT
            - MODEL_RESPONSE
        policyIds:
          description: List of policies to apply
          type: array
          items:
            type: string
        modelId:
          type: string
          description: The model id of the LLM to associate inference with
        clientId:
          type: string
          description: The client id of the sender
        metadata:
          type: object
          description: Metadata to be attached to the request
      required:
        - messages
        - textType
        - policyIds
    ReturnPolicyDto:
      type: object
      properties:
        id:
          type: string
          description: Id of the policy
        name:
          type: string
          description: Name of the policy
        description:
          type: string
          description: Description of the policy
        method:
          type: string
          description: Type of policy
          enum: &ref_9
            - PII
            - TOXICITY
            - ALIGNMENT
            - HALLUCINATION
            - RAG_HALLUCINATION
          externalDocs: &ref_10
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Types
            description: Information about policy types
        action:
          type: string
          description: The action to take if the policy is violated
          enum: &ref_11
            - BLOCK
            - WARN
            - REDACT
            - SANITIZE
            - NONE
          default: NONE
          externalDocs: &ref_12
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Actions
            description: Information about policy actions
        methodParams:
          type: object
          description: >-
            The arguments for the policy. These differ depending on the policy
            type
          externalDocs: &ref_13
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Method%20Params
            description: Information on policy types
        decisionParams:
          type: object
          description: >-
            The parameters for determining the policy action from outputs. These
            differ depending on the policy type
          externalDocs: &ref_14
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Decision%20Params
            description: Information on policy types
        applicableTo:
          type: string
          description: Which type of message the policy should apply to
          enum: &ref_15
            - INPUT
            - OUTPUT
            - ALL
          default: ALL
        created_at:
          format: date-time
          type: string
          description: Creation time of the policy
        creatorId:
          type: string
          description: Creator id of the policy
      required:
        - id
        - name
        - description
        - method
        - action
        - methodParams
        - decisionParams
        - applicableTo
        - created_at
        - creatorId
    AppliedPolicyDto:
      type: object
      properties:
        policy:
          description: Policy information
          allOf:
            - $ref: '#/components/schemas/ReturnPolicyDto'
        outputs:
          type: object
          description: Outputs from the policy
          externalDocs:
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Outputs
            description: Output object
        action:
          type: string
          description: Action taken after applying the policy
          externalDocs:
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Actions
            description: Information about policy actions
      required:
        - policy
        - outputs
        - action
    ReturnAnalyzeDto:
      type: object
      properties:
        text:
          type: string
          description: Text that was analyzed
        textType:
          type: string
          description: Whether the text was a prompt or response
          enum: &ref_0
            - MODEL_INPUT
            - MODEL_RESPONSE
        finalAction:
          type: string
          description: Final action based on all of the applied policies
          enum:
            - BLOCK
            - WARN
            - REDACT
            - SANITIZE
            - NONE
        appliedPolicies:
          description: List of policies that were applied
          type: array
          items:
            $ref: '#/components/schemas/AppliedPolicyDto'
        error:
          type: string
          description: 'Error message '
      required:
        - text
        - textType
        - finalAction
        - appliedPolicies
    PolicyWithFeedback:
      type: object
      properties:
        outputs:
          type: object
          description: Outputs from the policy
          externalDocs:
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Outputs
            description: Output object
        violated:
          type: boolean
          description: Whether the policy was violated
        feedback:
          type: object
          description: Feedback for the policy
        promptId:
          type: string
          description: Id of the prompt
        policy:
          description: Policy information
          allOf:
            - $ref: '#/components/schemas/ReturnPolicyDto'
        action:
          type: string
          description: Action taken
          enum:
            - BLOCK
            - WARN
            - REDACT
            - SANITIZE
            - NONE
      required:
        - outputs
        - violated
        - feedback
        - promptId
        - policy
        - action
    ReturnAnalysisWithFeedback:
      type: object
      properties:
        text:
          type: string
          description: Text that was analyzed
        textType:
          type: string
          description: Whether the text was a prompt or response
          enum: *ref_0
        appliedPolicies:
          description: List of policies that were applied
          type: array
          items:
            $ref: '#/components/schemas/PolicyWithFeedback'
      required:
        - text
        - textType
        - appliedPolicies
    ReturnLogEntry:
      type: object
      properties:
        timestamp:
          type: string
          description: UTC timestamp of interaction
        analyses:
          description: Analyses used during the interaction. Will be of length at most 2
          type: array
          items:
            $ref: '#/components/schemas/ReturnAnalysisWithFeedback'
        action:
          type: string
          description: Most severe action of the analyses
          enum:
            - BLOCK
            - WARN
            - REDACT
            - SANITIZE
            - NONE
      required:
        - timestamp
        - analyses
        - action
    FullReturnLogDto:
      type: object
      properties:
        logs:
          description: Paginated logs
          type: array
          items:
            $ref: '#/components/schemas/ReturnLogEntry'
        totalCount:
          type: number
          description: Total number of un-paginated logs
      required:
        - logs
        - totalCount
    OverviewSubStats:
      type: object
      properties:
        total:
          description: Frequency polygon of total entries. Buckets are the timestamps.
          type: array
          items:
            type: number
        flagged:
          description: Frequency polygon of flagged entries. Buckets are the timestamps.
          type: array
          items:
            type: number
      required:
        - total
        - flagged
    OverviewStats:
      type: object
      properties:
        MODEL_INPUT:
          description: Stats for all prompts
          allOf:
            - $ref: '#/components/schemas/OverviewSubStats'
        MODEL_RESPONSE:
          description: Stats for all LLM responses
          allOf:
            - $ref: '#/components/schemas/OverviewSubStats'
      required:
        - MODEL_INPUT
        - MODEL_RESPONSE
    PrivacySubStats:
      type: object
      properties:
        entity_types:
          type: object
          description: >-
            Flagged PII by category. Maps the entity type to list a frequency
            polygon of occurences. Buckets are the timestamps.
          additionalProperties:
            type: array
            items:
              type: number
          example:
            LOCATION:
              - 0
              - 37
        total:
          description: >-
            Frequency polygon of total PII violations. Buckets are the
            timestamps.
          type: array
          items:
            type: number
      required:
        - entity_types
        - total
    PrivacyStats:
      type: object
      properties:
        MODEL_INPUT:
          description: Stats for all prompts
          allOf:
            - $ref: '#/components/schemas/PrivacySubStats'
        MODEL_RESPONSE:
          description: Stats for all LLM responses
          allOf:
            - $ref: '#/components/schemas/PrivacySubStats'
      required:
        - MODEL_INPUT
        - MODEL_RESPONSE
    AggregateValue:
      type: object
      properties:
        value:
          type: number
          description: Actual value across the entire time period
        data:
          description: Frequency polygon of occurences. Buckets are the timestamps.
          type: array
          items:
            type: number
      required:
        - value
        - data
    ToxicitySubStats:
      type: object
      properties:
        total:
          description: >-
            Frequency polygon of total toxicity violations. Buckets are the
            timestamps.
          type: array
          items:
            type: number
        violation_rate:
          description: Fraction of entries classified as unsafe
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
      required:
        - total
        - violation_rate
    ToxicityStats:
      type: object
      properties:
        MODEL_INPUT:
          description: Stats for all prompts
          allOf:
            - $ref: '#/components/schemas/ToxicitySubStats'
        MODEL_RESPONSE:
          description: Stats for all LLM responses
          allOf:
            - $ref: '#/components/schemas/ToxicitySubStats'
      required:
        - MODEL_INPUT
        - MODEL_RESPONSE
    ContentPolicyStat:
      type: object
      properties:
        name:
          type: string
          description: Name of the policy
        num_violations:
          description: >-
            Frequency polygon of number of violations. Buckets are the
            timestamps.
          type: array
          items:
            type: number
        violation_rate:
          description: Fraction of entries violated
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
      required:
        - name
        - num_violations
        - violation_rate
    ContentSubStats:
      type: object
      properties:
        total:
          description: >-
            Frequency polygon of total content violations. Buckets are the
            timestamps.
          type: array
          items:
            type: number
        policies:
          type: object
          description: Breakdown per policy
          additionalProperties:
            $ref: '#/components/schemas/ContentPolicyStat'
      required:
        - total
        - policies
    ContentStats:
      type: object
      properties:
        MODEL_INPUT:
          description: Stats for all prompts
          allOf:
            - $ref: '#/components/schemas/ContentSubStats'
        MODEL_RESPONSE:
          description: Stats for all LLM responses
          allOf:
            - $ref: '#/components/schemas/ContentSubStats'
      required:
        - MODEL_INPUT
        - MODEL_RESPONSE
    HallucinationSubStats:
      type: object
      properties:
        total:
          description: >-
            Frequency polygon of total hallucination violations. Buckets are the
            timestamps.
          type: array
          items:
            type: number
        violation_rate:
          description: Fraction of entries classified as a hallucination
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        average:
          description: Average hallucination score
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
      required:
        - total
        - violation_rate
        - average
    HallucinationStats:
      type: object
      properties:
        MODEL_RESPONSE:
          description: Stats for all LLM responses
          allOf:
            - $ref: '#/components/schemas/HallucinationSubStats'
      required:
        - MODEL_RESPONSE
    RagHallucinationMetrics:
      type: object
      properties:
        violations:
          description: Number of violations for this metric
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        violation_rate:
          description: Fraction of entries classified as a hallucination for this metric
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        average:
          description: Average hallucination score for this metric
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
      required:
        - violations
        - violation_rate
        - average
    RagHallucinationSubStats:
      type: object
      properties:
        entries:
          description: Number of entries
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        violations:
          description: Number of violations
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        retrievalRelevance:
          description: Retrieval relevance stats
          allOf:
            - $ref: '#/components/schemas/RagHallucinationMetrics'
        responseRelevance:
          description: Response relevance stats
          allOf:
            - $ref: '#/components/schemas/RagHallucinationMetrics'
        responseFaithfulness:
          description: Response faithfulness stats
          allOf:
            - $ref: '#/components/schemas/RagHallucinationMetrics'
      required:
        - entries
        - violations
        - retrievalRelevance
        - responseRelevance
        - responseFaithfulness
    RagHallucinationStats:
      type: object
      properties:
        MODEL_RESPONSE:
          description: Stats for all LLM responses
          allOf:
            - $ref: '#/components/schemas/RagHallucinationSubStats'
      required:
        - MODEL_RESPONSE
    LatencyPercentile:
      type: object
      properties:
        percentile50:
          description: 50th percentile
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        percentile90:
          description: 90th percentile
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        percentile99:
          description: 99th percentile
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
      required:
        - percentile50
        - percentile90
        - percentile99
    LatencyRequests:
      type: object
      properties:
        successful:
          description: 'Number of successful requests '
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        failed:
          description: Number of failed requests
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
      required:
        - successful
        - failed
    LatencyFailureTypes:
      type: object
      properties:
        http4xx:
          description: Number of 4xx requests
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
        http5xx:
          description: Number of 5xx requests
          allOf:
            - $ref: '#/components/schemas/AggregateValue'
      required:
        - http4xx
        - http5xx
    LatencyStats:
      type: object
      properties:
        e2eLatency:
          description: End to end latency
          allOf:
            - $ref: '#/components/schemas/LatencyPercentile'
        inputGuardrailLatency:
          description: Input guardrail latency
          allOf:
            - $ref: '#/components/schemas/LatencyPercentile'
        outputGuardrailLatency:
          description: Output guardrail latency
          allOf:
            - $ref: '#/components/schemas/LatencyPercentile'
        llmCompletionLatency:
          description: LLM completion latency
          allOf:
            - $ref: '#/components/schemas/LatencyPercentile'
        requests:
          description: Types of requests
          allOf:
            - $ref: '#/components/schemas/LatencyRequests'
        failureTypes:
          description: Types of failed requests
          allOf:
            - $ref: '#/components/schemas/LatencyFailureTypes'
      required:
        - e2eLatency
        - inputGuardrailLatency
        - outputGuardrailLatency
        - llmCompletionLatency
        - requests
        - failureTypes
    RuleStats:
      type: object
      properties:
        ruleViolations:
          type: number
          description: Number of times a policy has been violated in the time period
        rulesActive:
          type: number
          description: Number of rules that are active (has been used in the time period)
      required:
        - ruleViolations
        - rulesActive
    ReturnStatsDto:
      type: object
      properties:
        overview:
          description: Stats of all usage logs
          allOf:
            - $ref: '#/components/schemas/OverviewStats'
        privacy:
          description: Stats for all PII logs
          allOf:
            - $ref: '#/components/schemas/PrivacyStats'
        toxicity:
          description: Stats for all toxicity logs
          allOf:
            - $ref: '#/components/schemas/ToxicityStats'
        alignment:
          description: Stats for all content logs
          allOf:
            - $ref: '#/components/schemas/ContentStats'
        hallucination:
          description: Stats for all hallucination logs
          allOf:
            - $ref: '#/components/schemas/HallucinationStats'
        ragHallucination:
          description: Stats for all RAG hallucination logs
          allOf:
            - $ref: '#/components/schemas/RagHallucinationStats'
        latency:
          description: Latency and request metrics
          allOf:
            - $ref: '#/components/schemas/LatencyStats'
        timestamps:
          description: >-
            List of UTC timestamps (in milliseconds) that represent the
            discretization buckets
          type: array
          items:
            type: number
        rules:
          description: Stats of all policies
          allOf:
            - $ref: '#/components/schemas/RuleStats'
      required:
        - overview
        - privacy
        - toxicity
        - alignment
        - hallucination
        - ragHallucination
        - latency
        - timestamps
        - rules
    ChatMessage:
      type: object
      properties:
        role:
          type: string
          description: Role
          enum: *ref_1
        content:
          type: string
          description: Text to send
      required:
        - role
        - content
    ChatDto:
      type: object
      properties:
        clientId:
          type: string
          description: The client id of the sender
        messages:
          description: OpenAI style messages to send to the LLM
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        metadata:
          type: object
          description: Metadata to be attached to the request
        overridePolicyIds:
          description: >-
            Explicit list of policies to apply instead of the ones attached to
            the model
          type: array
          items:
            type: string
      required:
        - messages
    ReturnSourceDto:
      type: object
      properties:
        user:
          type: string
          description: Id of the user who sent the request
        session:
          type: string
          description: Session id. Only present for chat requests
        model:
          type: string
          description: Model id. Only present for chat requests
        client:
          type: string
          description: Client id. Only present for chat requests
      required:
        - user
    ReturnChatDto:
      type: object
      properties:
        queryId:
          type: string
          description: Unique id of the query if chat request succeeds
        prompt:
          type: string
          description: Original user input
        preprocessedPrompt:
          type: string
          description: >-
            User input after policies are applied. This could contain the
            redacted iput. Not present if an error occurs.
        response:
          type: string
          description: >-
            Original LLM response. Not present if user input was blocked or an
            error occured when calling the LLM.
        desanitizedResponse:
          type: string
          description: >-
            If the user input had a sanitize policy applied, this field contains
            the result after reverse mapping redacted entities to plaintext.
        postprocessedResponse:
          type: string
          description: >-
            The LLM response after policies are applied. This could contain
            redacted input.
        ragContext:
          type: string
          description: >-
            Retrieved context from RAG endpoint. Only applicable to Custom RAG
            models.
        error:
          type: string
          description: Error message if one occurs
      required:
        - queryId
        - prompt
    FullReturnChatDto:
      type: object
      properties:
        source:
          description: Information about the request
          allOf:
            - $ref: '#/components/schemas/ReturnSourceDto'
        chat:
          description: Query lifecyle as policies are applied
          allOf:
            - $ref: '#/components/schemas/ReturnChatDto'
        metadata:
          type: object
          description: Any metadata that was attached to the request
        analyses:
          description: Analyses used during the interaction. Will be of length at most 2
          type: array
          items:
            $ref: '#/components/schemas/ReturnAnalyzeDto'
      required:
        - source
        - analyses
    UpdateModelPoliciesDto:
      type: object
      properties:
        policyIds:
          description: List of policy ids to activate on the model
          type: array
          items:
            type: string
        action:
          type: string
          description: Operation to perform on models
          enum:
            - ADD
            - REMOVE
            - REPLACE
      required:
        - policyIds
        - action
    CreatePolicyDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the policy
        description:
          type: string
          description: Description of the policy
        method:
          type: string
          description: Type of policy
          enum: &ref_2
            - PII
            - TOXICITY
            - ALIGNMENT
            - HALLUCINATION
            - RAG_HALLUCINATION
          externalDocs: &ref_3
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Types
            description: Information about policy types
        action:
          type: string
          description: The action to take if the policy is violated
          enum: &ref_4
            - BLOCK
            - WARN
            - REDACT
            - SANITIZE
            - NONE
          default: NONE
          externalDocs: &ref_5
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Actions
            description: Information about policy actions
        methodParams:
          type: object
          description: >-
            The arguments for the policy. These differ depending on the policy
            type
          externalDocs: &ref_6
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Method%20Params
            description: Information on policy types
        decisionParams:
          type: object
          description: >-
            The parameters for determining the policy action from outputs. These
            differ depending on the policy type
          externalDocs: &ref_7
            url: /docs/DynamoGuard/API%20Appendix/Policy%20Decision%20Params
            description: Information on policy types
        applicableTo:
          type: string
          description: Which type of message the policy should apply to
          enum: &ref_8
            - INPUT
            - OUTPUT
            - ALL
          default: ALL
      required:
        - name
        - method
        - action
        - methodParams
        - decisionParams
        - applicableTo
    UpdatePolicyDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the policy
        description:
          type: string
          description: Description of the policy
        method:
          type: string
          description: Type of policy
          enum: *ref_2
          externalDocs: *ref_3
        action:
          type: string
          description: The action to take if the policy is violated
          enum: *ref_4
          default: NONE
          externalDocs: *ref_5
        methodParams:
          type: object
          description: >-
            The arguments for the policy. These differ depending on the policy
            type
          externalDocs: *ref_6
        decisionParams:
          type: object
          description: >-
            The parameters for determining the policy action from outputs. These
            differ depending on the policy type
          externalDocs: *ref_7
        applicableTo:
          type: string
          description: Which type of message the policy should apply to
          enum: *ref_8
          default: ALL
    InputFeedbackDatapoint:
      type: object
      properties:
        prompt:
          type: string
          description: Prompt that feedback was given for
        isCompliant:
          type: boolean
          description: Whether the user rated the prompt as compliant
        feedback:
          type: boolean
          description: Reason for the isCompliant rating
      required:
        - prompt
        - isCompliant
        - feedback
    InputFeedback:
      type: object
      properties:
        promptId:
          type: string
          description: Prompt id
        review:
          description: Feedback submitted
          allOf:
            - $ref: '#/components/schemas/InputFeedbackDatapoint'
        createdAt:
          format: date-time
          type: string
          description: Timestamp of when feedback was added
        creator:
          type: string
          description: User who added the feedback
      required:
        - promptId
        - review
        - createdAt
        - creator
    AugmentedReturnPolicyDto:
      type: object
      properties:
        id:
          type: string
          description: Id of the policy
        name:
          type: string
          description: Name of the policy
        description:
          type: string
          description: Description of the policy
        method:
          type: string
          description: Type of policy
          enum: *ref_9
          externalDocs: *ref_10
        action:
          type: string
          description: The action to take if the policy is violated
          enum: *ref_11
          default: NONE
          externalDocs: *ref_12
        methodParams:
          type: object
          description: >-
            The arguments for the policy. These differ depending on the policy
            type
          externalDocs: *ref_13
        decisionParams:
          type: object
          description: >-
            The parameters for determining the policy action from outputs. These
            differ depending on the policy type
          externalDocs: *ref_14
        applicableTo:
          type: string
          description: Which type of message the policy should apply to
          enum: *ref_15
          default: ALL
        created_at:
          format: date-time
          type: string
          description: Creation time of the policy
        creatorId:
          type: string
          description: Creator id of the policy
        stage:
          type: string
          description: >-
            The stage of synthetic data generation the policy is in. Only
            available for content policies.
          enum: &ref_16
            - seed
            - reviewReady
            - improve
            - augment
            - approveReady
            - regenerate
        allowedBehaviors:
          description: List of allowed behaviors. Only available for content policies.
          type: array
          items:
            type: string
        disallowedBehaviors:
          description: List of disallowed behaviors. Only available for content policies.
          type: array
          items:
            type: string
        feedback:
          description: Feedback for policy. Only applicable to content policies
          allOf:
            - $ref: '#/components/schemas/InputFeedback'
        status:
          type: string
          description: The status of the policy.
        models:
          description: Models that policy is attached to
          type: array
          items:
            type: string
      required:
        - id
        - name
        - description
        - method
        - action
        - methodParams
        - decisionParams
        - applicableTo
        - created_at
        - creatorId
    PopulatedCreator:
      type: object
      properties:
        id:
          type: string
          description: Id of the creator
        email:
          type: string
          description: Email of the creator
      required:
        - id
        - email
    AugmentedReturnPolicyWithPopulatedCreatorDto:
      type: object
      properties:
        id:
          type: string
          description: Id of the policy
        name:
          type: string
          description: Name of the policy
        description:
          type: string
          description: Description of the policy
        method:
          type: string
          description: Type of policy
          enum: *ref_9
          externalDocs: *ref_10
        action:
          type: string
          description: The action to take if the policy is violated
          enum: *ref_11
          default: NONE
          externalDocs: *ref_12
        methodParams:
          type: object
          description: >-
            The arguments for the policy. These differ depending on the policy
            type
          externalDocs: *ref_13
        decisionParams:
          type: object
          description: >-
            The parameters for determining the policy action from outputs. These
            differ depending on the policy type
          externalDocs: *ref_14
        applicableTo:
          type: string
          description: Which type of message the policy should apply to
          enum: *ref_15
          default: ALL
        created_at:
          format: date-time
          type: string
          description: Creation time of the policy
        creatorId:
          type: string
          description: Creator id of the policy
        stage:
          type: string
          description: >-
            The stage of synthetic data generation the policy is in. Only
            available for content policies.
          enum: *ref_16
        allowedBehaviors:
          description: List of allowed behaviors. Only available for content policies.
          type: array
          items:
            type: string
        disallowedBehaviors:
          description: List of disallowed behaviors. Only available for content policies.
          type: array
          items:
            type: string
        feedback:
          description: Feedback for policy. Only applicable to content policies
          allOf:
            - $ref: '#/components/schemas/InputFeedback'
        status:
          type: string
          description: The status of the policy.
        models:
          description: Models that policy is attached to
          type: array
          items:
            type: string
        creator:
          description: Information about the policy creator
          allOf:
            - $ref: '#/components/schemas/PopulatedCreator'
      required:
        - id
        - name
        - description
        - method
        - action
        - methodParams
        - decisionParams
        - applicableTo
        - created_at
        - creatorId
        - creator
    AllAugmentedReturnPoliciesDto:
      type: object
      properties:
        total:
          type: number
          description: Total number of policies
        policies:
          description: List of policies
          type: array
          items:
            $ref: '#/components/schemas/AugmentedReturnPolicyWithPopulatedCreatorDto'
      required:
        - total
        - policies
    UpdatePolicyModelsDto:
      type: object
      properties:
        modelIds:
          description: List of model ids to add/remove policy to
          type: array
          items:
            type: string
        action:
          type: string
          description: Operation to perform on models
          enum:
            - ADD
            - REMOVE
            - REPLACE
      required:
        - modelIds
        - action
    CreateModelDto:
      type: object
      properties:
        name:
          type: string
          description: Display name for the model
        key:
          type: string
          description: Unique identifier for the model (usually UUID)
        type:
          type: string
          description: Type of model
          enum:
            - REMOTE
            - LOCAL
            - THIRD_PARTY
            - LOCAL_GUARDRAIL
        useCase:
          type: string
          description: Intended use case for the model
          example: chat
        config:
          type: object
          properties:
            remoteModelApiProvider:
              type: string
              description: The API provider
              enum:
                - openai
                - azure
                - anthropic
                - custom
            remoteModelApiInstance:
              type: string
              description: The specific model instance
              example: gpt-4
            remoteModelEndpoint:
              type: string
              description: The API endpoint URL
            apiKey:
              type: string
              description: The API key for authentication (will be encrypted)
            apiVersion:
              type: string
              description: Required only for Azure provider
            awsRegion:
              type: string
              description: Required only for AWS services
            modelType:
              type: string
              description: Used when provider is custom
          required:
            - remoteModelApiProvider
            - remoteModelApiInstance
            - apiKey
      required:
        - name
        - key
        - type
        - useCase
        - config
    ReturnModelDto:
      type: object
      properties:
        id:
          type: string
          description: Model ID
        name:
          type: string
          description: Display name for the model
        key:
          type: string
          description: Unique identifier for the model
        type:
          type: string
          description: Type of model
        useCase:
          type: string
          description: Intended use case for the model
        config:
          type: object
          properties:
            remoteModelApiProvider:
              type: string
              description: The API provider
            remoteModelApiInstance:
              type: string
              description: The specific model instance
            remoteModelEndpoint:
              type: string
              description: The API endpoint URL
            apiVersion:
              type: string
              description: API version (for Azure)
            awsRegion:
              type: string
              description: AWS region
            modelType:
              type: string
              description: Custom model type
          description: Model configuration (API key excluded for security)
        metadata:
          type: object
          properties:
            userEmail:
              type: string
              description: Email of the creator
            modelType:
              type: string
              description: Model type from provider
            source:
              type: string
              description: Source of the model
            contributors:
              type: array
              items:
                type: string
              description: List of contributors with owner
          description: Additional model metadata
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
      required:
        - id
        - name
        - key
        - type
        - useCase
        - config
        - metadata
        - created_at
