UpGuard threatmonitoring API
The threatmonitoring API from UpGuard — 9 operation(s) for threatmonitoring.
OpenAPI Specification
swagger: '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
host: cyber-risk.upguard.com
basePath: /api/public
schemes:
- https
consumes:
- application/json
produces:
- application/json
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:
- type: string
format: uuid
description: UUID of the result whose details we require
name: uuid
in: query
required: true
responses:
'200':
description: A detailed threat response
schema:
$ref: '#/definitions/GetThreatDetailsResponsePayloadBody'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/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:
- type: string
format: uuid
description: The unique identifier of the threat to close
name: uuid
in: query
required: true
- enum:
- false_positive
- risk_accepted
- remediated
type: string
description: 'The reason for closing the threat. Must be one of: false_positive, risk_accepted, remediated'
name: reason
in: query
required: true
- type: string
description: The justification for accepting the risk (required if reason is 'risk_accepted')
name: justification
in: query
- enum:
- content_removed_or_privatised
- affected_users_credentials_reset
- system_patched
- requested_takedown
- compensating_controls
- other
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
- type: string
description: Additional details for the remediation reason (required if remediation_reason is 'other')
name: remediation_description
in: query
responses:
'200':
description: The closed threat
schema:
$ref: '#/definitions/CloseThreatV1ResponsePayloadBody'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/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:
- name: Body
in: body
schema:
$ref: '#/definitions/AddThreatCommentV1RequestBody'
- type: string
format: uuid
description: The unique identifier of the threat to add a comment to
name: uuid
in: query
required: true
- type: integer
format: int64
example: 100000000000000
description: Optional parent comment ID if this is a reply to another comment
name: parent_id
in: query
- type: boolean
default: false
description: Optional flag to mark the comment as private. Only valid for threats under remediation.
name: private
in: query
responses:
'200':
description: The comment that was created.
schema:
$ref: '#/definitions/ThreatComment'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/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:
- enum:
- dark_web
- open_web
- social_media
type: string
description: Limit findings to this threat monitoring module.
name: module
in: query
- enum:
- last_twenty_four_hours
- last_seven_days
- last_thirty_days
- last_three_months
- last_six_months
- last_twelve_months
- all_time
type: string
default: all_time
description: The period within which results have been detected.
name: date_period
in: query
- type: string
default: UTC
description: The timezone for DatePeriod as per the IANA Time Zone database. Default is UTC.
name: date_period_timezone
in: query
- type: array
items:
type: string
collectionFormat: multi
example: mydomain.com
description: A list of matching transforms to filter results by. Repeat the parameter to supply multiple values.
name: transforms
in: query
- type: array
items:
enum:
- critical
- high
- medium
- low
- info
type: string
collectionFormat: multi
description: A list of matching severities to filter results by. Repeat the parameter to supply multiple values.
name: severities
in: query
- 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
collectionFormat: multi
description: A list of matching threat types to filter results by. Repeat the parameter to supply multiple values.
name: threat_types
in: query
- 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
collectionFormat: multi
description: A list of matching source types to filter results by. Repeat the parameter to supply multiple values.
name: source_types
in: query
- type: boolean
default: false
description: Limits threats to those auto-dismissed by an AI analyst
name: auto_dismissed
in: query
- type: array
items:
enum:
- dismissed
- dismissed_by_rule
- smart_filtered
- remediated
- waived
type: string
collectionFormat: multi
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
- enum:
- open
- investigating
- remediating
- closed
type: string
description: Limits the set of threat results based on their current status
name: threat_status
in: query
responses:
'200':
description: A count of threats
schema:
$ref: '#/definitions/GetThreatMonitoringResultsCountResponsePayloadBody'
'403':
description: Account does not have access to requested entities
schema:
$ref: '#/definitions/endpointError'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/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:
- type: string
format: uuid
description: The unique identifier of the threat to assign an investigator to
name: uuid
in: query
required: true
- type: string
example: user@yourcompany.com
description: The email address of the investigator to assign
name: investigator_email
in: query
required: true
responses:
'200':
description: The threat with its assigned investigator
schema:
$ref: '#/definitions/AssignThreatInvestigatorV1ResponsePayloadBody'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/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:
- enum:
- dark_web
- open_web
- social_media
type: string
description: Limit findings to this threat monitoring module.
name: module
in: query
- enum:
- last_twenty_four_hours
- last_seven_days
- last_thirty_days
- last_three_months
- last_six_months
- last_twelve_months
- all_time
type: string
default: all_time
description: The period within which results have been detected.
name: date_period
in: query
- type: string
default: UTC
description: The timezone for DatePeriod as per the IANA Time Zone database. Default is UTC.
name: date_period_timezone
in: query
- type: array
items:
type: string
collectionFormat: multi
example: mydomain.com
description: A list of matching transforms to filter results by. Repeat the parameter to supply multiple values.
name: transforms
in: query
- type: array
items:
enum:
- critical
- high
- medium
- low
- info
type: string
collectionFormat: multi
description: A list of matching severities to filter results by. Repeat the parameter to supply multiple values.
name: severities
in: query
- 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
collectionFormat: multi
description: A list of matching threat types to filter results by. Repeat the parameter to supply multiple values.
name: threat_types
in: query
- 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
collectionFormat: multi
description: A list of matching source types to filter results by. Repeat the parameter to supply multiple values.
name: source_types
in: query
- type: boolean
default: false
description: Limits threats to those auto-dismissed by an AI analyst
name: auto_dismissed
in: query
- type: array
items:
enum:
- dismissed
- dismissed_by_rule
- smart_filtered
- remediated
- waived
type: string
collectionFormat: multi
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
- enum:
- open
- investigating
- remediating
- closed
type: string
description: Limits the set of threat results based on their current status
name: threat_status
in: query
- maximum: 2000
type: integer
format: int64
default: 50
description: The page size of results to return. If not supplied, default is 50.
name: page_size
in: query
- type: string
description: The `next_page_token` from a previous request, use this to get the next page of results.
name: page_token
in: query
- type: boolean
default: false
description: Include the text snippet in results. Defaults to false.
name: include_snippets
in: query
- type: string
default: date_alerted:desc
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
responses:
'200':
description: A list of threats
schema:
$ref: '#/definitions/GetThreatMonitoringResultsResponsePayloadBody'
'403':
description: Account does not have access to requested entities
schema:
$ref: '#/definitions/endpointError'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/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:
- name: Body
in: body
schema:
$ref: '#/definitions/CreateThreatRemediationRequestV1RequestBody'
- type: string
format: uuid
description: The unique identifier of the threat to place into remediation
name: uuid
in: query
required: true
- type: string
example: user@yourcompany.com
description: The email address to assign the remediation request to
name: email
in: query
required: true
- type: string
description: The title for the remediation request. If not provided, will use the threat title
name: title
in: query
- type: string
format: date-time
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
- 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
- type: boolean
default: false
description: If true, copies all threat comments to the remediation request
name: copy_threat_comments
in: query
responses:
'200':
description: The remediation request that was created
schema:
$ref: '#/definitions/CreateThreatRemediationRequestV1ResponsePayloadBody'
'400':
description: The request was malformed (e.g. invalid JSON body)
schema:
$ref: '#/definitions/endpointError'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/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:
- type: string
format: uuid
description: The UUID of the threat whose remediation request should be closed
name: uuid
in: query
required: true
- enum:
- remediated
- waived
type: string
description: 'The reason for closing the remediation request. Must be one of: remediated, waived'
name: reason
in: query
required: true
- type: string
description: The description of the reason (required if reason is 'waived')
name: reason_description
in: query
responses:
'200':
description: The closed remediation request
schema:
$ref: '#/definitions/CloseThreatRemediationRequestV1ResponsePayloadBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/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:
- type: string
format: uuid
description: The unique identifier of the threat to reopen
name: uuid
in: query
required: true
- type: string
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
responses:
'200':
description: The reopened threat
schema:
$ref: '#/definitions/ReopenThreatV1ResponsePayloadBody'
'404':
description: There was a problem with the request
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
definitions:
DataLeakExternalAPIThreatAdditionalAttributes:
type: object
properties:
has_password:
type: boolean
leak_discover_date:
type: string
format: date-time
leak_name:
type: string
leak_publish_date:
type: string
format: date-time
leak_size:
type: integer
format: int64
leak_tags:
type: array
items:
$ref: '#/definitions/DataLeakTag'
login:
type: string
masked_password:
$ref: '#/definitions/MaskedPassword'
website:
type: string
RedditPostExternalAPIThreatAdditionalAttributes:
type: object
properties:
author_id:
type: string
author_is_blocked:
type: boolean
author_username:
type: string
comments_count:
type: integer
format: int64
created_time:
type: string
is_gallery:
type: boolean
is_original_content:
type: boolean
is_video:
type: boolean
post_id:
type: string
post_url:
type: string
score:
type: integer
format: int64
subreddit:
type: string
subreddit_id:
type: string
subreddit_subscribers:
type: integer
format: int64
subreddit_type:
type: string
text:
type: string
timestamp:
type: string
title:
type: string
total_awards_received:
type: integer
format: int64
upvote_ratio:
type: number
format: double
whitelist_status:
type: integer
format: int64
TwitterProfileExternalAPIThreatAdditionalAttributes:
type: object
properties:
created_time:
type: string
description:
type: string
external_url:
type: string
favorites_count:
type: integer
format: int64
followers_count:
type: integer
format: int64
friends_count:
type: integer
format: int64
full_name:
type: string
is_verified:
type: boolean
listed_count:
type: integer
format: int64
location:
type: string
media_count:
type: integer
format: int64
profile_id:
type: string
statuses_count:
type: integer
format: int64
username:
type: string
InstagramProfileExternalAPIThreatAdditionalAttributes:
type: object
properties:
age_group:
type: string
biography:
type: string
business_category:
type: array
items:
type: string
external_url:
type: string
followers_count:
type: integer
format: int64
followings_count:
type: integer
format: int64
full_name:
type: string
gender:
type: string
highlight_reels_count:
type: integer
format: int64
is_business_account:
type: boolean
is_joined_recently:
type: boolean
is_private:
type: boolean
is_verified:
type: boolean
langs:
type: array
items:
type: string
last_update:
type: string
latest_location_id:
type: string
posts_count:
type: integer
format: int64
profile_id:
type: string
public_email:
type: string
public_phone_country_code:
type: string
public_phone_number:
type: string
username:
type: string
LinkedInUserProfileExternalAPIThreatAdditionalAttributes:
type: object
properties:
city:
type: string
connections_count:
type: integer
format: int64
country:
type: string
country_full_name:
type: string
facebook_profile_id:
type: string
first_name:
type: string
follower_count:
type: integer
format: int64
full_name:
type: string
github_profile_id:
type: string
headline:
type: string
last_fetched_at:
type: string
last_name:
type: string
linkedin_profile_url:
type: string
location_str:
type: string
occupation:
type: string
personal_emails:
type: array
items:
type: string
personal_phone_numbers:
type: array
items:
type: string
public_identifier:
type: string
state:
type: string
summary:
type: string
twitter_p
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upguard/refs/heads/main/openapi/upguard-threatmonitoring-api-openapi.yml