UpGuard risks 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 Risks API
  version: 1.13.2
servers:
- url: https://cyber-risk.upguard.com/api/public
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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableRisk'
        '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'
  /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:
      - description: ID of the risk to fetch details for
        name: risk_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Risk details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableRiskV2'
        '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'
  /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:
      - description: Filter by risk category
        name: category
        in: query
        schema:
          type: string
      - description: Filter by risk severity
        name: severity
        in: query
        schema:
          type: string
          enum:
          - info
          - low
          - medium
          - high
          - critical
      responses:
        '200':
          description: Available risks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailableRiskV2'
        '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'
  /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:
      - description: Minimum severity for the risks
        name: min_severity
        in: query
        schema:
          type: string
          enum:
          - info
          - low
          - medium
          - high
          - critical
          default: info
      - description: Include metadata for risks
        name: include_meta
        in: query
        schema:
          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
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A list of detected risks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRisksV1RespBody'
        '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'
  /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:
      - 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
        schema:
          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
        schema:
          type: string
          format: date-time
      - 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
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Risks introduced and resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RisksDiffResponsePayloadBody'
        '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'
  /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:
      - example: upguard.com
        description: The primary hostname of the vendor to return risks for
        name: primary_hostname
        in: query
        required: true
        schema:
          type: string
      - description: Minimum severity for the risks
        name: min_severity
        in: query
        schema:
          type: string
          enum:
          - info
          - low
          - medium
          - high
          - critical
          default: info
      - description: 'Include metadata for risks,

          `include_meta` and ''exclude_hostnames'' cannot both be true'
        name: include_meta
        in: query
        schema:
          type: boolean
          default: false
      - description: 'Exclude hostnames for risks,

          `include_meta` and ''exclude_hostnames'' cannot both be true'
        name: exclude_hostnames
        in: query
        schema:
          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
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A list of detected risks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRisksV1RespBody'
        '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'
  /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:
      - 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
        schema:
          type: array
          items:
            type: string
      - 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
        schema:
          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
        schema:
          type: boolean
      - 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
        schema:
          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
        schema:
          type: integer
          format: int64
      - example: Acme
        description: Filter vendors whose name starts with the given prefix (case-insensitive).
        name: name_prefix
        in: query
        schema:
          type: string
      - example:
        - 123
        - 456
        description: Filter to only return vendors with the specified vendor IDs.
        name: vendor_ids
        in: query
        schema:
          type: array
          items:
            type: integer
            format: int64
      - 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
        schema:
          type: boolean
      - example:
        - 1
        - 2
        description: 'Filter watched vendors to those in the specified tiers.

          Valid values: 1-5.'
        name: vendor_tiers
        in: query
        schema:
          type: array
          items:
            type: integer
            format: int64
      - 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
        schema:
          type: array
          items:
            type: string
      - example: false
        description: If true, will return only vendors with a published assessment.
        name: assessed_vendors_only
        in: query
        schema:
          type: boolean
      - 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
        schema:
          type: array
          items:
            type: integer
            format: int64
      - 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
        schema:
          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
        schema:
          type: string
          format: date-time
      - example: false
        description: If true, filter to vendors added before vendor_date_added_end.
        name: vendor_date_added_before
        in: query
        schema:
          type: boolean
      - example: true
        description: If true, filter to vendors added between start and end dates.
        name: vendor_date_added_between
        in: query
        schema:
          type: boolean
      - 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
        schema:
          type: integer
          format: int64
      - 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
        schema:
          type: string
      responses:
        '200':
          description: VendorRiskOverviewV1Response is the response for the vendor risk overview endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorRiskOverviewV1ResponsePayload'
        '403':
          description: Account does not have access to requested entities
          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'
  /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:
      - example: upguard.com
        description: The primary hostname for a vendor
        name: vendor_primary_hostname
        in: query
        required: true
        schema:
          type: string
      - 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
        schema:
          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
        schema:
          type: string
          format: date-time
      - 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
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Risks introduced and resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RisksDiffResponsePayloadBody'
        '403':
          description: Your API key does not have permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: The vendor was not found.
          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'
  /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:
      - description: The date to use as the starting point for determining risks introduced/resolved (RFC 3339 format).
        name: start_date
        in: query
        required: true
        schema:
          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
        schema:
          type: string
          format: date-time
      - description: 'The token of the page to be returned.

          Will return the first page if left blank.'
        name: page_token
        in: query
        schema:
          type: string
      - 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
        schema:
          type: integer
          format: int64
          default: 20
          maximum: 200
          minimum: 10
      responses:
        '200':
          description: Risks introduced and resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorsRisksDiffResponsePayloadBody'
        '403':
          description: Your API key does not have permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: The vendor was not found.
          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'
  /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:
      - description: The risk_id to filter by
        name: risk_id
        in: query
        required: true
        schema:
          type: string
      - description: The vendor's internal ID.
        name: vendor_id
        in: query
        schema:
          type: integer
          format: int64
      - description: The vendor's primary hostname
        name: vendor_primary_hostname
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalVendorHostnamesWithRiskResponse'
        '403':
          description: Account does not have access to requested entities
          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'
  /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:
      - description: Restricts the questionnaire risks returned to a specific watched vendor by ID
        name: vendor_id
        in: query
        schema:
          type: integer
          format: int64
      - description: Restricts the questionnaire risks returned to a specific watched vendor by vendor primary hostname
        name: primary_hostname
        in: query
        schema:
          type: string
      - description: Restricts the questionnaire risks returned to a specific questionnaire by ID
        name: questionnaire_id
        in: query
        schema:
          type: integer
          format: int64
      - description: 'The token of the page to be returned.

          Will return the first page if left blank.'
        name: page_token
        in: query
        schema:
          type: string
      - 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
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Questionnaire risks for specific watched vendors or questionnaire instances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionnaireRisksResponsePayloadBody'
        '403':
          description: Account does not have access to requested entities
          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'
  /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:
      - description: Restricts the questionnaire risks returned to a specific watched vendor by ID
        name: vendor_id
        in: query
        schema:
          type: integer
          format: int64
      - description: Restricts the questionnaire risks returned to a specific watched vendor by vendor primary hostname
        name: primary_hostname
        in: query
        schema:
          type: string
      - description: Restricts the questionnaire risks returned to a specific questionnaire by ID
        name: questionnaire_id
        in: query
        schema:
          type: integer
          format: int64
      - description: 'The token of the page to be returned.

          Will return the first page if left blank.'
        name: page_token
        in: query
        schema:
          type: string
      - 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
        schema:
          type: integer
          format: int64
      - description: Indicates that waived risks should not be returned in the risk set
        name: ignore_waived_risks
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Questionnaire risks for specific watched vendors or questionnaire instances, including waiver details if appropriate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionnaireRisksResponsePayloadBodyV2'
        '403':
          description: Account does not have access to requested entities
          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 int

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