UpGuard bulk API

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 bulk 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: 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:
      - type: string
        description: The `page_token` from a previous request, use this to get the next page of results.
        name: page_token
        in: query
      - maximum: 2000
        minimum: 10
        type: integer
        format: int64
        default: 200
        description: The number of results to return per page.
        name: page_size
        in: query
      - type: boolean
        default: false
        description: Whether to sort the results in descending order.
        name: sort_desc
        in: query
      - type: boolean
        default: false
        description: Omit the scan information, i.e. risks, score and last scanned at.
        name: omit_scan_info
        in: query
      - type: boolean
        default: false
        description: Omit the vendor information for a hostname in the response.
        name: omit_vendor
        in: query
      - type: boolean
        default: false
        description: Omit the labels for a hostname in the response.
        name: omit_labels
        in: query
      - type: boolean
        default: false
        description: Exclude active hostnames from the results.
        name: exclude_active
        in: query
      - type: boolean
        default: false
        description: Exclude inactive hostnames from the results.
        name: exclude_inactive
        in: query
      - type: array
        items:
          type: string
        default: 'false'
        description: Filter results to only hostnames that have all the provided labels.
        name: labels
        in: query
      responses:
        '200':
          description: Returns the list of hostnames and their risks.
          schema:
            $ref: '#/definitions/BulkListHostnamesV1ResponseBody'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
    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
      parameters:
      - name: BulkRegisterHostnamesV1RequestBody
        in: body
        schema:
          $ref: '#/definitions/BulkRegisterHostnamesV1RequestBody'
      responses:
        '200':
          description: Returns the number of newly registered hostnames as well as the number of remaining slots.
          schema:
            $ref: '#/definitions/BulkRegisterHostnamesV1ResponseBody'
        '402':
          description: The requested action would exceed the limits of your contract.
          schema:
            $ref: '#/definitions/endpointError'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
    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
      parameters:
      - name: BulkDeregisterHostnamesV1RequestBody
        in: body
        schema:
          $ref: '#/definitions/BulkDeregisterHostnamesV1RequestBody'
      responses:
        '200':
          description: Returns the number of deregistered hostnames as well as the number of remaining slots.
          schema:
            $ref: '#/definitions/BulkDeregisterHostnamesV1ResponseBody'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
  /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.
          schema:
            $ref: '#/definitions/BulkGetHostnamesStatsV1ResponseBody'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
  /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:
      - type: string
        format: hostname
        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
      - type: boolean
        default: false
        description: Omit the scan information, i.e. risks, score and last scanned at.
        name: omit_scan_info
        in: query
      - type: boolean
        default: false
        description: Omit the vendor information for a hostname in the response.
        name: omit_vendor
        in: query
      - type: boolean
        default: false
        description: Omit the labels for a hostname in the response.
        name: omit_labels
        in: query
      responses:
        '200':
          description: Returns the details of the hostname.
          schema:
            $ref: '#/definitions/BulkHostname'
        '403':
          description: Your API key does not have permission to perform this action.
          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'
  /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:
      - type: string
        format: hostname
        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
      - example: '["network", "data"]'
        description: Labels list
        name: labels
        in: body
        schema:
          type: array
          items:
            type: string
      responses:
        '204':
          description: ' Successful response is empty'
        '403':
          description: Your API key does not have permission to perform this action.
          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:
  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
  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
  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
  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: '#/definitions/BulkRisk'
      vendor:
        $ref: '#/definitions/BulkVendor'
  BulkListHostnamesV1ResponseBody:
    type: object
    properties:
      hostnames:
        description: The list of hostnames.
        type: array
        items:
          $ref: '#/definitions/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
  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
  endpointError:
    description: Error details coming from an endpoint
    type: object
    properties:
      error:
        description: A description of the error
        type: string
  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
  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
  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
securityDefinitions:
  API key in header:
    type: apiKey
    in: header
    name: Authorization