UpGuard domains 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 domains 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: domains
paths:
  /domain:
    get:
      description: 'Returns the details for a domain. It will return 422 when requesting details of an inactive domain.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - domains
      summary: Retrieve details for a domain
      operationId: domain_details
      parameters:
      - type: string
        description: The hostname for which to return the details, e.g. "upguard.com"
        name: hostname
        in: query
        required: true
      responses:
        '200':
          description: Domain details
          schema:
            $ref: '#/definitions/GetDomainDetailsV1RespBody'
        '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'
  /domain/labels:
    put:
      description: 'Assign labels to a domain. To remove all labels pass an empty list.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - domains
      summary: Assign labels to a domain
      operationId: domain_update_labels
      parameters:
      - type: string
        description: The hostname to update labels for
        name: hostname
        in: query
        required: true
      - type: array
        items:
          type: string
        description: The labels to assign to the domain. You can pass an empty array to remove all labels.
        name: labels
        in: query
        required: true
      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'
  /domains:
    get:
      description: 'Returns a list of domains for your account.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - domains
      summary: Get a list of domains
      operationId: domains
      parameters:
      - type: boolean
        default: true
        description: Retrieve active domains
        name: active
        in: query
      - type: boolean
        default: true
        description: Retrieve inactive domains
        name: inactive
        in: query
      - type: array
        items:
          type: string
        description: Filter result by the provided labels
        name: labels
        in: query
      - 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: 1000
        description: The number of results to return per page.
        name: page_size
        in: query
      - enum:
        - domain
        - active
        - automated_score
        - scanned_at
        type: string
        default: domain
        description: 'The value to sort the domains by


          If not specified will default to `domain` and set `sort_desc` to `true`'
        name: sort_by
        in: query
      - type: boolean
        default: false
        description: Whether or not to sort the results in descending order
        name: sort_desc
        in: query
      responses:
        '200':
          description: A list of domains
          schema:
            $ref: '#/definitions/GetDomainsV1RespBody'
        '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'
    put:
      description: 'Add a list of custom domains to your account.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - domains
      summary: Add custom domains
      operationId: add_custom_domains
      parameters:
      - type: array
        items:
          type: string
        description: A comma separated list of hostnames to add
        name: hostnames
        in: query
        required: true
      - type: array
        items:
          type: string
        description: The labels to add to the hostnames
        name: labels
        in: query
      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'
    delete:
      description: 'Remove custom domains from your account.


        Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
      tags:
      - domains
      summary: Remove custom domains
      operationId: remove_custom_domains
      parameters:
      - type: array
        items:
          type: string
        description: A comma separated list of hostnames to remove. Only hostnames or labels can be specified not both
        name: hostnames
        in: query
      - type: array
        items:
          type: string
        description: A list of labels whose hostnames will be removed. All custom domains with at least one of the provided labels will be removed. Only hostnames or labels can be specified not both
        name: labels
        in: query
      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:
  Category:
    description: Category values cannot be changed after first use, as they're referenced in storage.
    type: string
    title: Category values represent risk categories.
  Domain:
    type: object
    properties:
      active:
        description: The status of the domain
        type: boolean
      automated_score:
        description: The score of the domain. If the domain is active or hasn't been scanned yet this field will be absent
        type: integer
        format: int64
      hostname:
        description: The hostname
        type: string
      labels:
        description: The labels associated with the domain
        type: array
        items:
          type: string
      primary_domain:
        description: Flag indicating the primary domain for the account
        type: boolean
      scanned_at:
        description: The time the domain was scanned. If the domain is inactive or hasn't been scanned yet this field will be absent
        type: string
        format: date-time
  Severity:
    type: integer
    format: int64
  endpointError:
    description: Error details coming from an endpoint
    type: object
    properties:
      error:
        description: A description of the error
        type: string
  GetDomainsV1RespBody:
    type: object
    properties:
      domains:
        description: The list of domains
        type: array
        items:
          $ref: '#/definitions/Domain'
      next_page_token:
        description: 'The token to be used to retrieve the next page of results.

          Will not be returned if there are no more results.'
        type: string
      total_results:
        description: The total number of domains found.
        type: integer
        format: int64
  CheckResult:
    type: object
    properties:
      actual:
        description: The found properties of the check
        type: array
        items:
          $ref: '#/definitions/Property'
      category:
        $ref: '#/definitions/Category'
      checked_at:
        description: The time the check was performed in RFC3339 format
        type: string
        format: date-time
      description:
        description: The description of the check performed
        type: string
      expected:
        description: The expected properties of the check
        type: array
        items:
          $ref: '#/definitions/Property'
      id:
        description: The ID of the check
        type: string
      pass:
        description: Flag indicating whether the check passed or not
        type: boolean
      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:
        $ref: '#/definitions/Severity'
      severityName:
        description: The severity fo the risk in human-readable form
        type: string
        enum:
        - pass
        - info
        - low
        - medium
        - high
        - critical
      sources:
        description: 'Sources contains information about the source of a check

          e.g. the IP addresses it was found on, or a domain name'
        type: array
        items:
          type: string
      title:
        description: The title of the check
        type: string
  Property:
    type: object
    properties:
      property:
        description: The name of the property
        type: string
      value:
        description: The value of the property
        type: string
  GetDomainDetailsV1RespBody:
    type: object
    properties:
      a_records:
        description: The list of A records associated with the domain. This field will be omitted if no A records were associated with the domain
        type: array
        items:
          type: string
      automated_score:
        description: The score for the domain. If the domain has not been scanned or no score is present this field will be omitted.
        type: integer
        format: int64
      check_results:
        description: The results of the domain scan. This field will be omitted if the domain has not been scanned or no results are available.
        type: array
        items:
          $ref: '#/definitions/CheckResult'
      hostname:
        description: The hostname of the domain
        type: string
      labels:
        description: The labels associated with the domain. This field will be omitted if no labels are present.
        type: array
        items:
          type: string
      scanned_at:
        description: The time the domain was scanned in RFC3339 format
        type: string
        format: date-time
      waived_check_results:
        description: The waived risks for this domain. This field will be omitted if no waived risks are present.
        type: array
        items:
          $ref: '#/definitions/CheckResult'
securityDefinitions:
  API key in header:
    type: apiKey
    in: header
    name: Authorization