UpGuard risks API
The risks API from UpGuard — 13 operation(s) for risks.
The risks API from UpGuard — 13 operation(s) for risks.
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 risks 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: risks
paths:
/available_risks:
get:
description: 'Returns a list of available risks in the UpGuard platform with detailed info. Please note this version of the endpoint has been deprecated, and v2 should be used instead.
Required API key permissions: `Platform` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of available risks in the platform
operationId: available_risks
deprecated: true
responses:
'200':
description: Available risks
schema:
$ref: '#/definitions/AvailableRisk'
'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'
/available_risks/risk:
get:
description: 'Returns the details for a risk.
Required API key permissions: `Platform` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get details for a risk in the platform
operationId: risk
parameters:
- type: string
description: ID of the risk to fetch details for
name: risk_id
in: query
required: true
responses:
'200':
description: Risk details
schema:
$ref: '#/definitions/AvailableRiskV2'
'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'
/available_risks/v2:
get:
description: 'Returns a list of available risks in the UpGuard platform with detailed info.
Some risks in the platform are generic risks like "exposed_service:*". The values of some of the fields for these risks
depends on the details of the risk, e.g. which particular service is exposed. As such these fields are omitted from the response.
To get the full details for a specific risk, e.g. "exposed_service:FTP", use the risk details endpoint which will return
the full information for the particular service.
Required API key permissions: `Platform` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of available risks in the platform
operationId: available_risks_v2
parameters:
- type: string
description: Filter by risk category
name: category
in: query
- enum:
- info
- low
- medium
- high
- critical
type: string
description: Filter by risk severity
name: severity
in: query
responses:
'200':
description: Available risks
schema:
type: array
items:
$ref: '#/definitions/AvailableRiskV2'
'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'
/risks:
get:
description: 'Returns a list of risks that have been detected for your account.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of active risks for your account
operationId: risks
parameters:
- enum:
- info
- low
- medium
- high
- critical
type: string
default: info
description: Minimum severity for the risks
name: min_severity
in: query
- type: boolean
default: false
description: Include metadata for risks
name: include_meta
in: query
- type: boolean
default: false
description: 'Include sources for risks, e.g. the hostname and/or IP addresses the risk was detected on, including ports
when available'
name: include_sources
in: query
responses:
'200':
description: A list of detected risks
schema:
$ref: '#/definitions/GetRisksV1RespBody'
'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'
/risks/diff:
get:
description: 'Returns a list of the risks introduced and risks resolved for domains or IPs between two dates.
The start_date must be in the last 2 years.
Previously provisional risks that are now scored will appear in the list of risks introduced.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of risk changes for your account
operationId: org_risks_diff
parameters:
- type: string
format: date-time
description: The date to use as the starting point for determining risks introduced/resolved (RFC 3339 format). Must be in the last 2 years.
name: start_date
in: query
required: true
- type: string
format: date-time
description: The date to use as the final state for determining risks introduced/resolved (RFC 3339 format). If not provided, the latest risks will be used.
name: end_date
in: query
- type: boolean
default: false
description: Include sources for risks, e.g. the hostname and/or IP addresses the risk was detected on, including ports
name: include_sources
in: query
responses:
'200':
description: Risks introduced and resolved
schema:
$ref: '#/definitions/RisksDiffResponsePayloadBody'
'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'
/risks/vendors:
get:
description: 'Returns a list of risks that have been detected for a particular vendor.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of active risks for a vendor
operationId: vendor_risks
parameters:
- type: string
example: upguard.com
description: The primary hostname of the vendor to return risks for
name: primary_hostname
in: query
required: true
- enum:
- info
- low
- medium
- high
- critical
type: string
default: info
description: Minimum severity for the risks
name: min_severity
in: query
- type: boolean
default: false
description: 'Include metadata for risks,
`include_meta` and ''exclude_hostnames'' cannot both be true'
name: include_meta
in: query
- type: boolean
default: false
description: 'Exclude hostnames for risks,
`include_meta` and ''exclude_hostnames'' cannot both be true'
name: exclude_hostnames
in: query
- type: boolean
default: false
description: 'Include sources for risks, e.g. the hostname and/or IP addresses the risk was detected on, including ports
when available'
name: include_sources
in: query
responses:
'200':
description: A list of detected risks
schema:
$ref: '#/definitions/GetRisksV1RespBody'
'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'
/risks/vendors/all:
get:
description: 'Returns an overview of all risks affecting vendors that match the specified filter criteria or all vendors.
This endpoint provides a consolidated view of cybersecurity risks.
The response includes the total number of vendors matching your filter and a list of all risks found,
with details about how many vendors are affected by each risk.
Results are paginated. Use the `page_size` parameter to control how many results are returned per page
(default: 100, max: 2000). Use the `next_page_token` from the response to retrieve subsequent pages.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get portfolio risk profile overview
operationId: vendor_risk_overview_params
parameters:
- type: array
items:
type: string
example:
- label1
- label2
- label3
description: 'Filter on vendor labels using the label’s name. By default, any matching vendor will be
returned. Use vendor_label_ids_match_all to require all labels to be present. If the label
does not exist, 422 will be returned.'
name: vendor_labels
in: query
- type: boolean
example: true
description: 'If true, will only return vendors that match ALL of the provided label IDs.
If false or omitted, vendors matching ANY of the provided labels will be returned.'
name: vendor_label_ids_match_all
in: query
- type: boolean
example: false
description: If true, will include vendors that have no labels applied when vendor_label_ids is provided.
name: include_unlabeled
in: query
- type: integer
format: int64
example: 300
description: 'Filter vendors to those with a score greater than or equal to this value.
Valid range: 0-950.'
name: min_score
in: query
- type: integer
format: int64
example: 700
description: 'Filter vendors to those with a score less than or equal to this value.
Valid range: 0-950.'
name: max_score
in: query
- type: string
example: Acme
description: Filter vendors whose name starts with the given prefix (case-insensitive).
name: name_prefix
in: query
- type: array
items:
type: integer
format: int64
example:
- 123
- 456
description: Filter to only return vendors with the specified vendor IDs.
name: vendor_ids
in: query
- type: boolean
example: false
description: 'If true, will only return vendors that DO NOT match ANY of the provided label IDs.
This is mutually exclusive with vendor_label_ids_match_all.'
name: vendor_label_ids_do_not_match
in: query
- type: array
items:
type: integer
format: int64
example:
- 1
- 2
description: 'Filter watched vendors to those in the specified tiers.
Valid values: 1-5.'
name: vendor_tiers
in: query
- type: array
items:
type: string
example:
- portfolio1
- portfolio2
description: 'Filter by portfolio IDs. Only vendors in these portfolios will be returned.
If the portofilo does not exist, 422 will be returned.'
name: portfolios
in: query
- type: boolean
example: false
description: If true, will return only vendors with a published assessment.
name: assessed_vendors_only
in: query
- type: array
items:
type: integer
format: int64
example:
- 1
- 2
description: 'Filter by questionnaire type IDs. Only vendors with these questionnaire types will be returned.
Available questionnaire types can be found at /api/public/vendor/questionnaire_types.'
name: questionnaire_type_ids
in: query
- type: string
format: date-time
example: '2024-01-01T00:00:00Z'
description: 'Start of date added range filter (RFC3339 format).
Filters vendors added on or after this date.'
name: vendor_date_added_start
in: query
- type: string
format: date-time
example: '2024-12-31T23:59:59Z'
description: 'End of date added range filter (RFC3339 format).
Filters vendors added on or before this date.'
name: vendor_date_added_end
in: query
- type: boolean
example: false
description: If true, filter to vendors added before vendor_date_added_end.
name: vendor_date_added_before
in: query
- type: boolean
example: true
description: If true, filter to vendors added between start and end dates.
name: vendor_date_added_between
in: query
- type: integer
format: int64
example: 100
description: 'The number of results to return per page.
Valid values range from 10 to 2000.
Defaults to 100 if not specified.'
name: page_size
in: query
- type: string
example: eyJ2IjoxMDAsImUiOjE3MDAwMDAwMDAsImgiOiJhYmMxMjMifQ==
description: 'Token to retrieve a specific page of results.
Omit to retrieve the first page.
Use the `next_page_token` from the previous response to get the next page.'
name: page_token
in: query
responses:
'200':
description: VendorRiskOverviewV1Response is the response for the vendor risk overview endpoint.
schema:
$ref: '#/definitions/VendorRiskOverviewV1ResponsePayload'
'403':
description: Account does not have access to requested entities
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'
/risks/vendors/diff:
get:
description: 'Returns a list of the risks introduced and risks resolved for domains or IPs between two dates.
The maximum allowed interval is 30 days.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of risk changes for a vendor
operationId: vendor_risks_diff
parameters:
- type: string
example: upguard.com
description: The primary hostname for a vendor
name: vendor_primary_hostname
in: query
required: true
- type: string
format: date-time
description: The date to use as the starting point for determining risks introduced/resolved (RFC 3339 format). Must be in the last 2 years.
name: start_date
in: query
required: true
- type: string
format: date-time
description: The date to use as the final state for determining risks introduced/resolved (RFC 3339 format). If not provided, the latest risks will be used.
name: end_date
in: query
- type: boolean
default: false
description: 'Include sources for risks, e.g. the hostname and/or IP addresses the risk was detected on, including ports
when available'
name: include_sources
in: query
responses:
'200':
description: Risks introduced and resolved
schema:
$ref: '#/definitions/RisksDiffResponsePayloadBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'404':
description: The vendor was not found.
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'
/risks/vendors/diffs:
get:
description: 'Returns a list of the risks introduced and risks resolved for domains or IPs between two dates across your monitored vendors.
The maximum allowed interval is 30 days.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of risk changes for monitored vendors
operationId: vendors_risks_diff
parameters:
- type: string
format: date-time
description: The date to use as the starting point for determining risks introduced/resolved (RFC 3339 format).
name: start_date
in: query
required: true
- type: string
format: date-time
description: The date to use as the final state for determining risks introduced/resolved (RFC 3339 format). If not provided, the latest risks will be used.
name: end_date
in: query
- type: string
description: 'The token of the page to be returned.
Will return the first page if left blank.'
name: page_token
in: query
- maximum: 200
minimum: 10
type: integer
format: int64
default: 20
description: 'The number of results to return per page.
Valid values range from 10 to 200.
Defaults to 20 if unset.'
name: page_size
in: query
responses:
'200':
description: Risks introduced and resolved
schema:
$ref: '#/definitions/VendorsRisksDiffResponsePayloadBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'404':
description: The vendor was not found.
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'
/risks/vendors/hostnames:
get:
description: 'Returns a list of hostnames for a specific vendor that are affected by a specific risk.
This endpoint provides detailed information about which hostnames have failed a particular
risk check including the detection date and last scan date.
The vendor can be identified either by `vendor_id` (for webless vendors) or `vendor_primary_hostname` (for vendors with or without a web presence).
Exactly one identifier must be provided.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get vendor hostnames affected by a risk
operationId: get_vendor_hostnames_with_risk_params
parameters:
- type: string
description: The risk_id to filter by
name: risk_id
in: query
required: true
- type: integer
format: int64
description: The vendor's internal ID.
name: vendor_id
in: query
- type: string
description: The vendor's primary hostname
name: vendor_primary_hostname
in: query
responses:
'200':
description: ''
schema:
$ref: '#/definitions/ExternalVendorHostnamesWithRiskResponse'
'403':
description: Account does not have access to requested entities
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'
/risks/vendors/questionnaires:
get:
description: 'Returns a list of currently open questionnaire risks for one or more of an account''s watched vendors. Please note this version of the endpoint has been deprecated, and v2 should be used instead.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get a list of questionnaire risks for one or more watched vendors or a specific questionnaire
operationId: vendor_questionnaire_risks
deprecated: true
parameters:
- type: integer
format: int64
description: Restricts the questionnaire risks returned to a specific watched vendor by ID
name: vendor_id
in: query
- type: string
description: Restricts the questionnaire risks returned to a specific watched vendor by vendor primary hostname
name: primary_hostname
in: query
- type: integer
format: int64
description: Restricts the questionnaire risks returned to a specific questionnaire by ID
name: questionnaire_id
in: query
- type: string
description: 'The token of the page to be returned.
Will return the first page if left blank.'
name: page_token
in: query
- type: integer
format: int64
description: 'The number of risks to return per page.
This Integer between 10 and 2000 defaults to 1000 if not supplied.'
name: page_size
in: query
responses:
'200':
description: Questionnaire risks for specific watched vendors or questionnaire instances
schema:
$ref: '#/definitions/QuestionnaireRisksResponsePayloadBody'
'403':
description: Account does not have access to requested entities
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'
/risks/vendors/questionnaires/v2:
get:
description: 'Returns a list of currently open questionnaire risks for one or more of an account''s watched vendors, including information on whether waivers exist for each risk.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: (V2) Get a list of questionnaire risks for one or more watched vendors or a specific questionnaire
operationId: vendor_questionnaire_risks_v2
parameters:
- type: integer
format: int64
description: Restricts the questionnaire risks returned to a specific watched vendor by ID
name: vendor_id
in: query
- type: string
description: Restricts the questionnaire risks returned to a specific watched vendor by vendor primary hostname
name: primary_hostname
in: query
- type: integer
format: int64
description: Restricts the questionnaire risks returned to a specific questionnaire by ID
name: questionnaire_id
in: query
- type: string
description: 'The token of the page to be returned.
Will return the first page if left blank.'
name: page_token
in: query
- type: integer
format: int64
description: 'The number of risks to return per page.
This Integer between 10 and 2000 defaults to 1000 if not supplied.'
name: page_size
in: query
- type: boolean
description: Indicates that waived risks should not be returned in the risk set
name: ignore_waived_risks
in: query
responses:
'200':
description: Questionnaire risks for specific watched vendors or questionnaire instances, including waiver details if appropriate
schema:
$ref: '#/definitions/QuestionnaireRisksResponsePayloadBodyV2'
'403':
description: Account does not have access to requested entities
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'
/risks/vendors_with_risk:
get:
description: 'Returns a list of vendors that are affected by a specific risk.
This endpoint provides detailed information about vendors that have failed a particular risk,
including vendor details, risk information, and waiver status.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- risks
summary: Get vendors affected by a risk
operationId: get_vendors_with_risk_params
parameters:
- type: array
items:
type: string
example:
- label1
- label2
- label3
description: 'Filter on vendor labels using the label’s name. By default, any matching vendor will be
returned. Use vendor_label_ids_match_all to require all labels to be present. If the label
does not exist, 422 will be returned.'
name: vendor_labels
in: query
- type: boolean
example: true
description: 'If true, will only return vendors that match ALL of the provided label IDs.
If false or omitted, vendors matching ANY of the provided labels will be returned.'
name: vendor_label_ids_match_all
in: query
- type: boolean
example: false
description: If true, will include vendors that have no labels applied when vendor_label_ids is provided.
name: include_unlabeled
in: query
- type: integer
format: int64
example: 300
description: 'Filter vendors to those with a score greater than or equal to this value.
Valid range: 0-950.'
name: min_score
in: query
- type: integer
format: int64
example: 700
description: 'Filter vendors to those with a score less than or equal to this value.
Valid range: 0-950.'
name: max_score
in: query
- type: string
example: Acme
description: Filter vendors whose name starts with the given prefix (case-insensitive).
name: name_prefix
in: query
- type: array
items:
type: integer
format: int64
example:
- 123
- 456
description: Filter to only return vendors with the specified vendor IDs.
name: vendor_ids
in: query
- type: boolean
example: false
description: 'If true, will only return vendors that DO NOT match ANY of the provided label IDs.
This is mutually exclusive with vendor_label_ids_match_all.'
name: vendor_label_ids_do_not_match
in: query
- type: array
items:
type: integer
format: int64
example:
- 1
- 2
description: 'Filter watched vendors to those in the specified tiers.
Valid values: 1-5.'
name: vendor_tiers
in: query
- type: array
items:
type: string
example:
- portfolio1
- portfolio2
description: 'Filter by portfolio IDs. Only vendors in these portfolios will be returned.
If the portofilo does not exist, 422 will be returned.'
name: portfolios
in: query
- type: boolean
example: false
description: If true, will return only vendors with a published assessment.
name: assessed_vendors_only
in: query
- type: array
items:
type: integer
format: int64
example:
- 1
- 2
description: 'Filter by questionnaire type IDs. Only vendors with these questionnaire types will be returned.
Available questionnaire types can be found at /api/public/vendor/questionnaire_types.'
name: questionnaire_type_ids
in: query
- type: string
format: date-time
example: '2024-01-01T00:00:00Z'
description: 'Start of date added range filter (RFC3339 format).
Filters vendors added on or after this date.'
name: vendor_date_added_start
in: query
- type: string
format: date-time
example: '2024-12-31T23:59:59Z'
description: 'End of date added range filter (RFC3339 format).
Filters vendors added on or before this date.'
name: vendor_date_added_end
in: query
- type: boolean
example: false
description: If tr
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upguard/refs/heads/main/openapi/upguard-risks-api-openapi.yml