UpGuard threatmonitoring API

openapi: 3.2.0
info:
  description: 'Access information from the CyberRisk platform programmatically using this API.


    You can find or generate an API key to access this API in your CyberRisk Account Settings.

    Please authorize all requests by setting the "Authorization" header to your api key.


    The base url for all public endpoints is https://cyber-risk.upguard.com/api/public'
  title: UpGuard CyberRisk breaches Threatmonitoring API
  version: 1.13.2
servers:
- url: https://cyber-risk.upguard.com/api/public
security:
- API key in header: []
tags:
- name: threatmonitoring
paths:
  /threatmonitoring/threat:
    get:
      description: 'Retrieve the detailed data for a specific threat, identified by UUID.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Get threat details
      operationId: threatmonitoring_details
      parameters:
      - description: UUID of the result whose details we require
        name: uuid
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: A detailed threat response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetThreatDetailsResponsePayloadBody'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
  /threatmonitoring/threat/close:
    post:
      description: 'Closes a specific threat, identified by UUID, with the given reason. The reason must be one of: false_positive, risk_accepted, remediated.


        For reason ''false_positive'': No additional parameters are required.

        For reason ''risk_accepted'': The ''justification'' parameter is required and must contain a free-form text explaining why the risk is accepted.

        For reason ''remediated'': The ''remediation_reason'' parameter is required and must be one of: content_removed_or_privatised, affected_users_credentials_reset, system_patched, requested_takedown, compensating_controls, other. If ''other'', the ''remediation_description'' parameter is also required.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Close threat
      operationId: threatmonitoring_close_threat
      parameters:
      - description: The unique identifier of the threat to close
        name: uuid
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - description: 'The reason for closing the threat. Must be one of: false_positive, risk_accepted, remediated'
        name: reason
        in: query
        required: true
        schema:
          type: string
          enum:
          - false_positive
          - risk_accepted
          - remediated
      - description: The justification for accepting the risk (required if reason is 'risk_accepted')
        name: justification
        in: query
        schema:
          type: string
      - description: 'The remediation reason. Must be one of: content_removed_or_privatised, affected_users_credentials_reset, system_patched, requested_takedown, compensating_controls, other (required if reason is ''remediated'')'
        name: remediation_reason
        in: query
        schema:
          type: string
          enum:
          - content_removed_or_privatised
          - affected_users_credentials_reset
          - system_patched
          - requested_takedown
          - compensating_controls
          - other
      - description: Additional details for the remediation reason (required if remediation_reason is 'other')
        name: remediation_description
        in: query
        schema:
          type: string
      responses:
        '200':
          description: The closed threat
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseThreatV1ResponsePayloadBody'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
  /threatmonitoring/threat/comment/add:
    post:
      description: 'Adds a comment to a specific threat, identified by UUID. Comments can only be added to threats in ''investigating'' or ''remediating'' state.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Add comment to threat
      operationId: threatmonitoring_add_comment
      parameters:
      - description: The unique identifier of the threat to add a comment to
        name: uuid
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - example: 100000000000000
        description: Optional parent comment ID if this is a reply to another comment
        name: parent_id
        in: query
        schema:
          type: integer
          format: int64
      - description: Optional flag to mark the comment as private. Only valid for threats under remediation.
        name: private
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The comment that was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreatComment'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddThreatCommentV1RequestBody'
  /threatmonitoring/threat/count:
    get:
      description: 'Returns the total count of Threat Monitoring threats for an organization matching the given filter.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Count threats
      operationId: threatmonitoring_results_count
      parameters:
      - description: Limit findings to this threat monitoring module.
        name: module
        in: query
        schema:
          type: string
          enum:
          - dark_web
          - open_web
          - social_media
      - description: The period within which results have been detected.
        name: date_period
        in: query
        schema:
          type: string
          enum:
          - last_twenty_four_hours
          - last_seven_days
          - last_thirty_days
          - last_three_months
          - last_six_months
          - last_twelve_months
          - all_time
          default: all_time
      - description: The timezone for DatePeriod as per the IANA Time Zone database. Default is UTC.
        name: date_period_timezone
        in: query
        schema:
          type: string
          default: UTC
      - example: mydomain.com
        description: A list of matching transforms to filter results by. Repeat the parameter to supply multiple values.
        name: transforms
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: A list of matching severities to filter results by. Repeat the parameter to supply multiple values.
        name: severities
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - critical
            - high
            - medium
            - low
            - info
            type: string
      - description: A list of matching threat types to filter results by. Repeat the parameter to supply multiple values.
        name: threat_types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - exposed_credentials
            - exposed_credentials_site
            - exposed_credentials_user
            - exposed_pii
            - malware
            - keyword_mention
            - confidential_business
            - brand_impersonation
            - denial_of_service
            - planned_intrusion
            - network_access_for_sale
            - data_for_sale
            - possible_data_breach
            - planned_attack
            - planned_violent_threat
            - planned_protest_activism
            - account_compromise
            - fraud_or_loss
            - complaint
            type: string
      - description: A list of matching source types to filter results by. Repeat the parameter to supply multiple values.
        name: source_types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - stealer_logs
            - forum
            - marketplace
            - ransomware_blog
            - icq
            - openbazaar
            - paste
            - blogs
            - news
            - social_media
            - code_repository
            - issue_tracker
            - package_repository
            - messaging
            - owned_domain
            - education_research
            - business_commercial
            - cloud_storage
            - cloud_services
            - community
            - conferences_events
            - cms
            - documentation
            - domain_tools
            - fin_services
            - govt_legal
            - healthcare
            - industrial_manufacture
            - job_board
            - media_entertainment
            - network_tool
            - personal_web
            - search_engine
            - sec_tools
            - software
            - sports
            - tech
            - vibe_coding_tool
            - mcp_registries
            - data_dump
            - exposed_service
            type: string
      - description: Limits threats to those auto-dismissed by an AI analyst
        name: auto_dismissed
        in: query
        schema:
          type: boolean
          default: false
      - description: Limits the set of threat results to those with a remediation status matching at least one entry provided. Repeat the parameter to supply multiple values.
        name: closed_status
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - dismissed
            - dismissed_by_rule
            - smart_filtered
            - remediated
            - waived
            type: string
      - description: Limits the set of threat results based on their current status
        name: threat_status
        in: query
        schema:
          type: string
          enum:
          - open
          - investigating
          - remediating
          - closed
      responses:
        '200':
          description: A count of threats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetThreatMonitoringResultsCountResponsePayloadBody'
        '403':
          description: Account does not have access to requested entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
  /threatmonitoring/threat/investigator/update:
    post:
      description: 'Assigns an investigator to a specific threat, identified by UUID, and places the threat into the investigating state.

        The investigator is identified by their email address and must be a member of the organization with ThreatMonitoringWrite permission.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Update threat's investigator
      operationId: threatmonitoring_assign_investigator
      parameters:
      - description: The unique identifier of the threat to assign an investigator to
        name: uuid
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - example: user@yourcompany.com
        description: The email address of the investigator to assign
        name: investigator_email
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The threat with its assigned investigator
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignThreatInvestigatorV1ResponsePayloadBody'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
  /threatmonitoring/threat/list:
    get:
      description: 'Retrieve Threat Monitoring threats for an organization.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: List threats
      operationId: threatmonitoring_results
      parameters:
      - description: Limit findings to this threat monitoring module.
        name: module
        in: query
        schema:
          type: string
          enum:
          - dark_web
          - open_web
          - social_media
      - description: The period within which results have been detected.
        name: date_period
        in: query
        schema:
          type: string
          enum:
          - last_twenty_four_hours
          - last_seven_days
          - last_thirty_days
          - last_three_months
          - last_six_months
          - last_twelve_months
          - all_time
          default: all_time
      - description: The timezone for DatePeriod as per the IANA Time Zone database. Default is UTC.
        name: date_period_timezone
        in: query
        schema:
          type: string
          default: UTC
      - example: mydomain.com
        description: A list of matching transforms to filter results by. Repeat the parameter to supply multiple values.
        name: transforms
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: A list of matching severities to filter results by. Repeat the parameter to supply multiple values.
        name: severities
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - critical
            - high
            - medium
            - low
            - info
            type: string
      - description: A list of matching threat types to filter results by. Repeat the parameter to supply multiple values.
        name: threat_types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - exposed_credentials
            - exposed_credentials_site
            - exposed_credentials_user
            - exposed_pii
            - malware
            - keyword_mention
            - confidential_business
            - brand_impersonation
            - denial_of_service
            - planned_intrusion
            - network_access_for_sale
            - data_for_sale
            - possible_data_breach
            - planned_attack
            - planned_violent_threat
            - planned_protest_activism
            - account_compromise
            - fraud_or_loss
            - complaint
            type: string
      - description: A list of matching source types to filter results by. Repeat the parameter to supply multiple values.
        name: source_types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - stealer_logs
            - forum
            - marketplace
            - ransomware_blog
            - icq
            - openbazaar
            - paste
            - blogs
            - news
            - social_media
            - code_repository
            - issue_tracker
            - package_repository
            - messaging
            - owned_domain
            - education_research
            - business_commercial
            - cloud_storage
            - cloud_services
            - community
            - conferences_events
            - cms
            - documentation
            - domain_tools
            - fin_services
            - govt_legal
            - healthcare
            - industrial_manufacture
            - job_board
            - media_entertainment
            - network_tool
            - personal_web
            - search_engine
            - sec_tools
            - software
            - sports
            - tech
            - vibe_coding_tool
            - mcp_registries
            - data_dump
            - exposed_service
            type: string
      - description: Limits threats to those auto-dismissed by an AI analyst
        name: auto_dismissed
        in: query
        schema:
          type: boolean
          default: false
      - description: Limits the set of threat results to those with a remediation status matching at least one entry provided. Repeat the parameter to supply multiple values.
        name: closed_status
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - dismissed
            - dismissed_by_rule
            - smart_filtered
            - remediated
            - waived
            type: string
      - description: Limits the set of threat results based on their current status
        name: threat_status
        in: query
        schema:
          type: string
          enum:
          - open
          - investigating
          - remediating
          - closed
      - description: The page size of results to return. If not supplied, default is 50.
        name: page_size
        in: query
        schema:
          type: integer
          format: int64
          default: 50
          maximum: 2000
      - description: The `next_page_token` from a previous request, use this to get the next page of results.
        name: page_token
        in: query
        schema:
          type: string
      - description: Include the text snippet in results. Defaults to false.
        name: include_snippets
        in: query
        schema:
          type: boolean
          default: false
      - description: 'List of fields to sort threats by, with optional :asc or :desc suffix per field.

          Allowed fields: date_alerted.

          Default direction is descending.'
        name: sort_by
        in: query
        schema:
          type: string
          default: date_alerted:desc
      responses:
        '200':
          description: A list of threats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetThreatMonitoringResultsResponsePayloadBody'
        '403':
          description: Account does not have access to requested entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
  /threatmonitoring/threat/remediation_request/add:
    post:
      description: 'Creates a remediation request for a specific threat, identified by UUID, and places the threat into the remediation state. The remediation request is assigned to the specified email address.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Add remediation request to threat
      operationId: threatmonitoring_remediation
      parameters:
      - description: The unique identifier of the threat to place into remediation
        name: uuid
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - example: user@yourcompany.com
        description: The email address to assign the remediation request to
        name: email
        in: query
        required: true
        schema:
          type: string
      - description: The title for the remediation request. If not provided, will use the threat title
        name: title
        in: query
        schema:
          type: string
      - description: Optional due date for the remediation request. Accepts YYYY-MM-DD (interpreted as UTC midnight) or RFC3339. Must not be in the past
        name: due_date
        in: query
        schema:
          type: string
          format: date-time
      - description: Optional reminder date for the remediation request. Requires due_date to be set. Accepts YYYY-MM-DD (interpreted as UTC midnight) or RFC3339. Must not be in the past
        name: reminder_date
        in: query
        schema:
          type: string
          format: date-time
      - description: If true, copies all threat comments to the remediation request
        name: copy_threat_comments
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The remediation request that was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateThreatRemediationRequestV1ResponsePayloadBody'
        '400':
          description: The request was malformed (e.g. invalid JSON body)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateThreatRemediationRequestV1RequestBody'
  /threatmonitoring/threat/remediation_request/close:
    post:
      description: 'Closes the remediation request for a specific threat, identified by UUID, by setting its status to ''Closed''. The threat must currently be in remediation.

        The reason must be one of: remediated, waived. For a reason of ''waived'' a description is required.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Close threat's remediation request
      operationId: threatmonitoring_remediation_close
      parameters:
      - description: The UUID of the threat whose remediation request should be closed
        name: uuid
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - description: 'The reason for closing the remediation request. Must be one of: remediated, waived'
        name: reason
        in: query
        required: true
        schema:
          type: string
          enum:
          - remediated
          - waived
      - description: The description of the reason (required if reason is 'waived')
        name: reason_description
        in: query
        schema:
          type: string
      responses:
        '200':
          description: The closed remediation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseThreatRemediationRequestV1ResponsePayloadBody'
        '403':
          description: Your API key does not have permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
  /threatmonitoring/threat/reopen:
    post:
      description: 'Reopens a closed threat, identified by UUID, and places it back into the investigating state.

        The user identified by `investigator_email` is assigned as the investigator; they must belong

        to your organization and have write permission for Threat Monitoring.


        The threat can only be reopened if:

        it is currently closed; and

        it is not linked to a remediation request.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - threatmonitoring
      summary: Reopen threat
      operationId: threatmonitoring_reopen_threat
      parameters:
      - description: The unique identifier of the threat to reopen
        name: uuid
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - example: user@yourcompany.com
        description: 'The email address of the user to assign as the investigator on reopen.

          The user must belong to your organization and have write permission for Threat Monitoring.'
        name: investigator_email
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The reopened threat
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReopenThreatV1ResponsePayloadBody'
        '404':
          description: There was a problem with the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
components:
  schemas:
    ThreatLabel:
      type: object
      properties:
        name:
          type: string
    ExternalAPIThreadEntry:
      type: object
      properties:
   

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