UpGuard domains API
The domains API from UpGuard — 3 operation(s) for domains.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/upguard-domains-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
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 Domains API
version: 1.13.2
servers:
- url: https://cyber-risk.upguard.com/api/public
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:
- description: The hostname for which to return the details, e.g. "upguard.com"
name: hostname
in: query
required: true
schema:
type: string
responses:
'200':
description: Domain details
content:
application/json:
schema:
$ref: '#/components/schemas/GetDomainDetailsV1RespBody'
'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'
/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:
- description: The hostname to update labels for
name: hostname
in: query
required: true
schema:
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
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.
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'
/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:
- description: Retrieve active domains
name: active
in: query
schema:
type: boolean
default: true
- description: Retrieve inactive domains
name: inactive
in: query
schema:
type: boolean
default: true
- description: Filter result by the provided labels
name: labels
in: query
schema:
type: array
items:
type: string
- 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: 1000
maximum: 2000
minimum: 10
- 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
schema:
type: string
enum:
- domain
- active
- automated_score
- scanned_at
default: domain
- description: Whether or not to sort the results in descending order
name: sort_desc
in: query
schema:
type: boolean
default: false
responses:
'200':
description: A list of domains
content:
application/json:
schema:
$ref: '#/components/schemas/GetDomainsV1RespBody'
'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'
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:
- description: A comma separated list of hostnames to add
name: hostnames
in: query
required: true
schema:
type: array
items:
type: string
- description: The labels to add to the hostnames
name: labels
in: query
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.
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'
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:
- description: A comma separated list of hostnames to remove. Only hostnames or labels can be specified not both
name: hostnames
in: query
schema:
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
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.
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'
components:
schemas:
CheckResult:
type: object
properties:
actual:
description: The found properties of the check
type: array
items:
$ref: '#/components/schemas/Property'
category:
$ref: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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
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
GetDomainsV1RespBody:
type: object
properties:
domains:
description: The list of domains
type: array
items:
$ref: '#/components/schemas/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
Severity:
type: integer
format: int64
Property:
type: object
properties:
property:
description: The name of the property
type: string
value:
description: The value of the property
type: string
Category:
description: Category values cannot be changed after first use, as they're referenced in storage.
type: string
title: Category values represent risk categories.
endpointError:
description: Error details coming from an endpoint
type: object
properties:
error:
description: A description of the error
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: '#/components/schemas/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: '#/components/schemas/CheckResult'
securitySchemes:
API_key_in_header:
type: apiKey
in: header
name: Authorization