UpGuard bulk 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 Bulk API
  version: 1.13.2
servers:
- url: https://cyber-risk.upguard.com/api/public
security:
- API key in header: []
tags:
- name: bulk
paths:
  /bulk/hostnames:
    get:
      description: 'Get the list of registered hostnames and their risks. You can use the omit_risks,

        omit_vendor, omit_score and omit_labels query parameter to turn off these information

        from the response and quickly get a list of registered hostnames.


        This is an add-on endpoint not available to all accounts. Please contact support for information about bulk endpoints and how to upgrade your account.


        Required API key permissions: `Admin` (select when creating API key in Account Settings)'
      tags:
      - bulk
      summary: List hostnames and their risks
      operationId: bulk_list_hostnames
      parameters:
      - description: The `page_token` from a previous request, use this to get the next page of results.
        name: page_token
        in: query
        schema:
          type: string
      - description: The number of results to return per page.
        name: page_size
        in: query
        schema:
          type: integer
          format: int64
          default: 200
          maximum: 2000
          minimum: 10
      - description: Whether to sort the results in descending order.
        name: sort_desc
        in: query
        schema:
          type: boolean
          default: false
      - description: Omit the scan information, i.e. risks, score and last scanned at.
        name: omit_scan_info
        in: query
        schema:
          type: boolean
          default: false
      - description: Omit the vendor information for a hostname in the response.
        name: omit_vendor
        in: query
        schema:
          type: boolean
          default: false
      - description: Omit the labels for a hostname in the response.
        name: omit_labels
        in: query
        schema:
          type: boolean
          default: false
      - description: Exclude active hostnames from the results.
        name: exclude_active
        in: query
        schema:
          type: boolean
          default: false
      - description: Exclude inactive hostnames from the results.
        name: exclude_inactive
        in: query
        schema:
          type: boolean
          default: false
      - description: Filter results to only hostnames that have all the provided labels.
        name: labels
        in: query
        schema:
          type: array
          items:
            type: string
          default: 'false'
      responses:
        '200':
          description: Returns the list of hostnames and their risks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkListHostnamesV1ResponseBody'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
    post:
      description: 'Register a list of hostnames to be scanned for risks. The provided hostnames must be fully qualified domain names

        or IPv4 addresses. Currently, a maximum of 1000 hostnames in a single request is supported. This will always replace

        the labels of currently registered hostnames and if the request has empty labels they will all be removed.


        This is an add-on endpoint not available to all accounts. Please contact support for information about bulk endpoints and how to upgrade your account.


        Required API key permissions: `Admin` (select when creating API key in Account Settings)'
      tags:
      - bulk
      summary: Register a list of hostnames to be scanned for risks
      operationId: bulk_register_hostnames
      responses:
        '200':
          description: Returns the number of newly registered hostnames as well as the number of remaining slots.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkRegisterHostnamesV1ResponseBody'
        '402':
          description: The requested action would exceed the limits of your contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '403':
          description: Your API key does not have permission to perform this action.
          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/BulkRegisterHostnamesV1RequestBody'
    delete:
      description: 'Deregister a list of hostnames. The provided hostnames must be fully qualified domain names

        or IPv4 addresses. Currently, a maximum of 1000 hostnames in a single request is supported.


        This is an add-on endpoint not available to all accounts. Please contact support for information about bulk endpoints and how to upgrade your account.


        Required API key permissions: `Admin` (select when creating API key in Account Settings)'
      tags:
      - bulk
      summary: Deregister a list of hostnames
      operationId: bulk_deregister_hostnames
      responses:
        '200':
          description: Returns the number of deregistered hostnames as well as the number of remaining slots.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeregisterHostnamesV1ResponseBody'
        '403':
          description: Your API key does not have permission to perform this action.
          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/BulkDeregisterHostnamesV1RequestBody'
  /bulk/hostnames/stats:
    get:
      description: 'Get statistics for the registered hostnames. This will return the number of registered hostnames, the number of

        remaining slots and the number of active and inactive hostnames


        This is an add-on endpoint not available to all accounts. Please contact support for information about bulk endpoints and how to upgrade your account.


        Required API key permissions: `Admin` (select when creating API key in Account Settings)'
      tags:
      - bulk
      summary: Get statistics around registered bulk hostnames
      operationId: bulk_get_hostnames_stats
      responses:
        '200':
          description: Returns the statistics for the registered hostnames.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkGetHostnamesStatsV1ResponseBody'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
  /bulk/hostnames/{hostname}:
    get:
      description: 'Get the details for a hostname. The provided hostname must be a fully

        qualified domain name or an IPv4 address.


        This is an add-on endpoint not available to all accounts. Please contact support for information about bulk endpoints and how to upgrade your account.


        Required API key permissions: `Admin` (select when creating API key in Account Settings)'
      tags:
      - bulk
      summary: Get the details for a hostname
      operationId: bulk_get_hostname_details
      parameters:
      - description: The hostname to fetch details for. It must be a fully qualified domain name or an IPv4 address.
        name: hostname
        in: path
        required: true
        schema:
          type: string
          format: hostname
      - description: Omit the scan information, i.e. risks, score and last scanned at.
        name: omit_scan_info
        in: query
        schema:
          type: boolean
          default: false
      - description: Omit the vendor information for a hostname in the response.
        name: omit_vendor
        in: query
        schema:
          type: boolean
          default: false
      - description: Omit the labels for a hostname in the response.
        name: omit_labels
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Returns the details of the hostname.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkHostname'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
  /bulk/hostnames/{hostname}/labels:
    put:
      description: 'Assign labels to a hostname replacing the existing ones if any. To remove all labels use an empty array in the request.


        This is an add-on endpoint not available to all accounts. Please contact support for information about bulk endpoints and how to upgrade your account.


        Required API key permissions: `Admin` (select when creating API key in Account Settings)'
      tags:
      - bulk
      summary: Assign new labels to a hostname
      operationId: bulk_hostname_put_labels
      parameters:
      - description: The hostname to fetch details for. It must be a fully qualified domain name or an IPv4 address.
        name: hostname
        in: path
        required: true
        schema:
          type: string
          format: hostname
      responses:
        '204':
          description: ' Successful response is empty'
        '403':
          description: Your API key does not have permission to perform this action.
          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:
              type: array
              items:
                type: string
        description: Labels list
components:
  schemas:
    BulkDeregisterHostnamesV1RequestBody:
      type: object
      properties:
        hostnames:
          description: The hostnames to deregister. Currently, a maximum of 1000 hostnames in a single request is supported.
          type: array
          items:
            type: string
            format: hostname
          example:
          - 8.8.8.8
          - example.com
    BulkVendor:
      type: object
      properties:
        id:
          description: The ID of the vendor.
          type: integer
          format: int64
          example: 123456789
        name:
          description: The name of the vendor.
          type: string
          example: Example Industries
        primary_hostname:
          description: The primary hostname of the vendor.
          type: string
          format: hostname
          example: example.com
    BulkRegisterHostnamesV1ResponseBody:
      type: object
      properties:
        registered:
          description: The number of newly registered hostnames.
          type: integer
          format: int64
          example: 4
        remaining:
          description: The number of remaining slots.
          type: integer
          format: int64
          example: 10
    BulkRegisterHostnamesV1RequestBody:
      type: object
      properties:
        hostnames:
          description: The hostnames to register. Currently, a maximum of 1000 hostnames in a single request is supported.
          type: array
          items:
            type: string
            format: hostname
          example:
          - 8.8.8.8
          - example.com
        labels:
          description: The labels to add to the registered hostnames. If they don't exist they will be created.
          type: array
          items:
            type: string
          example:
          - network
          - data
    BulkRisk:
      type: object
      properties:
        category:
          description: The risk category identifier
          type: string
          enum:
          - website_sec
          - email_sec
          - network_sec
          - ip_domain_reputation
          - brand_protect
          - attack_surface
          - dns
          - vulnerability_management
          - data_leakage
          - encryption
          - questionnaire_risks
          - vulns
          - typosquatting
          - emailexposures
          - dataleaks
          - additional_evidence
          example: vulnerability_management
        description:
          description: A long description of the risk
          type: string
          example: 'Remote code execution exploit chain consisting of 3 vulnerabilities in Microsoft Exchange Server: CVE-2021-34473, CVE-2021-34523 and CVE-2021-31207'
        finding:
          description: A short description of the finding
          type: string
          example: Vulnerable to CVE-2021-34473 (ProxyShell)
        id:
          description: The risk identifier
          type: string
          example: verified_vuln:CVE-2021-34473
        risk:
          description: A short description of the risk
          type: string
          example: Vulnerabilities
        riskSubtype:
          description: The subtype of the risk, e.g. the subtype of the verified_vuln:CVE-2021-34473 is CVE-2021-34473. This field will be empty if the risk has no subtype, e.g. for wp_version_exposed, or for generic risks like verified_vuln:* where the subtype is only determined when the full risk is specified.
          type: string
          example: CVE-2021-34473
        riskType:
          description: The type of the risk, e.g. the type of the verified_vuln:CVE-2021-34473 is verified_vuln
          type: string
          example: verified_vuln
        severity:
          description: The risk severity
          type: string
          enum:
          - pass
          - info
          - low
          - medium
          - high
          - critical
          example: critical
    BulkGetHostnamesStatsV1ResponseBody:
      type: object
      properties:
        active:
          description: The number of active hostnames.
          type: integer
          format: int64
          example: 900
        inactive:
          description: The number of inactive hostnames.
          type: integer
          format: int64
          example: 100
        registered:
          description: The number of registered hostnames.
          type: integer
          format: int64
          example: 1000
        remaining:
          description: The number of remaining available slots.
          type: integer
          format: int64
          example: 9000
    BulkDeregisterHostnamesV1ResponseBody:
      type: object
      properties:
        deregistered:
          description: The number of deregistered hostnames.
          type: integer
          format: int64
          example: 4
        remaining:
          description: The number of remaining slots.
          type: integer
          format: int64
          example: 10
    endpointError:
      description: Error details coming from an endpoint
      type: object
      properties:
        error:
          description: A description of the error
          type: string
    BulkListHostnamesV1ResponseBody:
      type: object
      properties:
        hostnames:
          description: The list of hostnames.
          type: array
          items:
            $ref: '#/components/schemas/BulkHostname'
        next_page_token:
          description: The token to be used to retrieve the next page of results. It will not be returned if there are no more results.
          type: string
          example: '123456789'
        total_results:
          description: The total number of hostnames found.
          type: integer
          format: int64
          example: 1000
    BulkHostname:
      type: object
      properties:
        active:
          description: The active state of the hostname. These will be omitted if the omit_scan_info query parameter is true.
          type: boolean
          example: true
        automated_score:
          description: The automated score of the hostname. This will be omitted if the omit_scan_info query parameter is true.
          type: integer
          format: int64
          maximum: 950
          minimum: 0
          example: 800
        hostname:
          description: The name of the hostname.
          type: string
          format: hostname
        labels:
          description: The list of labels associated with the hostname. This will be omitted if the omit_labels query parameter is true.
          type: array
          items:
            type: string
          example:
          - network
          - data
        last_scanned_at:
          description: The timestamp this hostname was last scanned at.
          type: string
          format: date-time
        risks:
          description: The list of risks associated with the hostname. These will be omitted if the omit_scan_info query parameter is true.
          type: array
          items:
            $ref: '#/components/schemas/BulkRisk'
        vendor:
          $ref: '#/components/schemas/BulkVendor'
  securitySchemes:
    API_key_in_header:
      type: apiKey
      in: header
      name: Authorization