OpenAPI Spec
View this specification or browse all our OpenAPI specifications on SwaggerHub.
openapi: 3.0.3
info:
title: DomainTools Iris API
version: 1.0.0
description: |
The new OpenAPI spec for DomainTools Iris endpoints.
servers:
- url: https://api.domaintools.com
description: DomainTools APIs
tags:
- name: Information
description:
Access the latest information about your account, including service
limits.
- name: Iris Detect
description: |
Iris Detect is an Internet infrastructure detection, monitoring, and enforcement tool.
It rapidly discovers malicious domains that are engaged in brand impersonation, risk-scores them within minutes, and supports your automation of detection, escalation, and enforcement actions.
- name: Iris Enrich
description: Designed to support high query volumes with batch processing and fast response times, the Iris Enrich API provides actionable insights-at-scale with enterprise-scale ingestion of DomainTools data
- name: Iris Investigate
description: |
The Iris Investigate API is ideally suited for investigate and orchestrate use cases at human scale. Identify threats, map adversary infrastructure, and streamline investigations.
security:
- hmac_auth: []
- header_auth: []
- open_key_auth: []
paths:
/v1/iris-detect/domains/:
patch:
operationId: patchDetectDomains
summary: Add and remove domains from Watchlist or Ignored lists.
tags: [Iris Detect]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistState'
responses:
'200':
$ref: '#/components/responses/DetectWatchlistOk'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
externalDocs:
url: https://docs.domaintools.com/api/iris/detect/reference/#add-remove-from-watchlist
/v1/iris-detect/domains/ignored/:
get:
operationId: getDetectIgnored
summary: Provide ignored domains for active monitors in an account.
tags: [Iris Detect]
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/appPartner'
- $ref: '#/components/parameters/appVersion'
- $ref: '#/components/parameters/changedSince'
- $ref: '#/components/parameters/discoveredBefore'
- $ref: '#/components/parameters/discoveredSince'
- $ref: '#/components/parameters/domainState'
- $ref: '#/components/parameters/escalatedSince'
- $ref: '#/components/parameters/includeDomainData'
- $ref: '#/components/parameters/irisContainsSearch'
- $ref: '#/components/parameters/irisResultsLimit'
- $ref: '#/components/parameters/monitorId'
- $ref: '#/components/parameters/mxExists'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/order'
- $ref: '#/components/parameters/preview'
- $ref: '#/components/parameters/riskScoreRanges'
- $ref: '#/components/parameters/sortDetect'
- $ref: '#/components/parameters/tlds'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DetectDomainList'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
externalDocs:
url: https://docs.domaintools.com/api/iris/detect/reference/#domains
/v1/iris-detect/domains/new/:
get:
operationId: getDetectNewDomains
summary: Provide newly discovered domains for active monitors in an account.
tags: [Iris Detect]
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/appPartner'
- $ref: '#/components/parameters/appVersion'
- $ref: '#/components/parameters/discoveredBefore'
- $ref: '#/components/parameters/discoveredSince'
- $ref: '#/components/parameters/includeDomainData'
- $ref: '#/components/parameters/irisContainsSearch'
- $ref: '#/components/parameters/irisResultsLimit'
- $ref: '#/components/parameters/monitorId'
- $ref: '#/components/parameters/mxExists'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/order'
- $ref: '#/components/parameters/preview'
- $ref: '#/components/parameters/riskScoreRanges'
- $ref: '#/components/parameters/sortDetect'
- $ref: '#/components/parameters/tlds'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DetectDomainList'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
externalDocs:
url: https://docs.domaintools.com/api/iris/detect/reference/#domains
/v1/iris-detect/domains/watched/:
get:
operationId: getDomainsWatched
summary: Provide recently changed or escalated domains for active monitors in an account.
tags: [Iris Detect]
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/appPartner'
- $ref: '#/components/parameters/appVersion'
- $ref: '#/components/parameters/changedSince'
- $ref: '#/components/parameters/discoveredBefore'
- $ref: '#/components/parameters/discoveredSince'
- $ref: '#/components/parameters/escalatedSince'
- $ref: '#/components/parameters/escalationTypes'
- $ref: '#/components/parameters/includeDomainData'
- $ref: '#/components/parameters/irisContainsSearch'
- $ref: '#/components/parameters/irisResultsLimit'
- $ref: '#/components/parameters/monitorId'
- $ref: '#/components/parameters/mxExists'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/order'
- $ref: '#/components/parameters/preview'
- $ref: '#/components/parameters/riskScoreRanges'
- $ref: '#/components/parameters/sortDetect'
- $ref: '#/components/parameters/tlds'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DetectDomainList'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
externalDocs:
url: https://docs.domaintools.com/api/iris/detect/reference/#domains
/v1/iris-detect/escalations/:
post:
operationId: postDetectEscalations
summary: Escalate internally and externally.
tags: [Iris Detect]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistEscalation'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Escalations'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
externalDocs:
url: https://docs.domaintools.com/api/iris/detect/reference/#escalate
/v1/iris-detect/monitors/:
get:
operationId: getDetectMonitors
summary: Retrieves monitors and monitor IDs for an account.
tags: [Iris Detect]
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/appPartner'
- $ref: '#/components/parameters/appVersion'
- $ref: '#/components/parameters/datetimeCountsSince'
- $ref: '#/components/parameters/includeCounts'
- $ref: '#/components/parameters/limitMonitors'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/order'
- $ref: '#/components/parameters/sortMonitorList'
responses:
'200':
$ref: '#/components/responses/DetectMonitorSuccess'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
externalDocs:
url: https://docs.domaintools.com/api/iris/detect/reference/#monitor-list
/v1/iris-enrich/:
get:
operationId: getIrisEnrich
summary: Returns results from a GET request to Iris Enrich.
tags: [Iris Enrich]
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/appPartner'
- $ref: '#/components/parameters/appVersion'
- $ref: '#/components/parameters/domainsQueryRequired'
- $ref: '#/components/parameters/parsedDomainRdapFlag'
- $ref: '#/components/parameters/parsedWhoisFlag'
- $ref: '#/components/parameters/responseFormat'
responses:
'200':
$ref: '#/components/responses/EnrichSuccess'
'206':
$ref: '#/components/responses/IrisPartialContent'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
'500':
$ref: '#/components/responses/IrisInternalServerError'
'503':
$ref: '#/components/responses/IrisServiceUnavailable'
externalDocs:
url: https://docs.domaintools.com/api/iris/enrich/
post:
operationId: postIrisEnrich
summary: Returns results from a POST request to Iris Enrich.
tags: [Iris Enrich]
requestBody:
$ref: '#/components/requestBodies/Enrich'
responses:
'200':
$ref: '#/components/responses/EnrichSuccess'
'206':
$ref: '#/components/responses/IrisPartialContent'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
'500':
$ref: '#/components/responses/IrisInternalServerError'
'503':
$ref: '#/components/responses/IrisServiceUnavailable'
externalDocs:
url: https://docs.domaintools.com/api/iris/enrich/
/v1/iris-investigate/:
get:
operationId: getIrisInvestigate
summary: Returns data from a GET request.
tags: [Iris Investigate]
description: Consider using POST for complex requests.
parameters:
- $ref: '#/components/parameters/active'
- $ref: '#/components/parameters/adsense'
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/appPartner'
- $ref: '#/components/parameters/appVersion'
- $ref: '#/components/parameters/createDate'
- $ref: '#/components/parameters/createDateWithin'
- $ref: '#/components/parameters/domainLastIp'
- $ref: '#/components/parameters/domainsQuery'
- $ref: '#/components/parameters/expirationDate'
- $ref: '#/components/parameters/firstSeenSince'
- $ref: '#/components/parameters/firstSeenWithin'
- $ref: '#/components/parameters/googleAnalytics'
- $ref: '#/components/parameters/mailserverDomain'
- $ref: '#/components/parameters/mailserverHost'
- $ref: '#/components/parameters/mailserverIp'
- $ref: '#/components/parameters/nameserverDomain'
- $ref: '#/components/parameters/nameserverHost'
- $ref: '#/components/parameters/nameserverIp'
- $ref: '#/components/parameters/notTaggedWithAll'
- $ref: '#/components/parameters/notTaggedWithAny'
- $ref: '#/components/parameters/parsedDomainRdapFlag'
- $ref: '#/components/parameters/parsedWhoisFlag'
- $ref: '#/components/parameters/redirectDomain'
- $ref: '#/components/parameters/registrant'
- $ref: '#/components/parameters/registrantOrg'
- $ref: '#/components/parameters/registrar'
- $ref: '#/components/parameters/responseFormat'
- $ref: '#/components/parameters/resultsPosition'
- $ref: '#/components/parameters/searchHash'
- $ref: '#/components/parameters/sslEmail'
- $ref: '#/components/parameters/sslHash'
- $ref: '#/components/parameters/sslOrg'
- $ref: '#/components/parameters/sslSubject'
- $ref: '#/components/parameters/taggedWithAll'
- $ref: '#/components/parameters/taggedWithAny'
- $ref: '#/components/parameters/topLevelDomain'
- $ref: '#/components/parameters/websiteTitle'
responses:
'200':
$ref: '#/components/responses/InvestigateSuccess'
'206':
$ref: '#/components/responses/IrisPartialContent'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
'500':
$ref: '#/components/responses/IrisInternalServerError'
'503':
$ref: '#/components/responses/IrisServiceUnavailable'
externalDocs:
url: https://docs.domaintools.com/api/iris/investigate/
post:
operationId: postIrisInvestigate
summary: Returns data from a POST request.
tags: [Iris Investigate]
description: The GET method is available for simple queries.
requestBody:
$ref: '#/components/requestBodies/Investigate'
responses:
'200':
$ref: '#/components/responses/InvestigateSuccess'
'206':
$ref: '#/components/responses/IrisPartialContent'
'400':
$ref: '#/components/responses/IrisBadRequest'
'401':
$ref: '#/components/responses/IrisUnauthorized'
'403':
$ref: '#/components/responses/IrisForbidden'
'404':
$ref: '#/components/responses/IrisNotFound'
'500':
$ref: '#/components/responses/IrisInternalServerError'
'503':
$ref: '#/components/responses/IrisServiceUnavailable'
externalDocs:
url: https://docs.domaintools.com/api/iris/investigate/
components:
parameters:
active:
in: query
name: active
description: |
Set to `true` to only return domains that have either an entry in the global Domain Name System, OR are listed as registered by the registry.
Set to `false` to only return domains that do not have an entry in the global DNS, AND are not listed as registered by the registry.
schema:
type: boolean
adsense:
in: query
name: adsense
description: Domains with a Google AdSense tracking code.
schema:
$ref: '#/components/schemas/IdentifierString'
appName:
in: query
name: app_name
description: Appliance, module, or playbook, or any combination of these.
schema:
$ref: '#/components/schemas/IdentifierString'
appPartner:
in: query
name: app_partner
description: Your product name.
schema:
$ref: '#/components/schemas/IdentifierString'
appVersion:
in: query
name: app_version
description: Version of your integration/connector.
schema:
$ref: '#/components/schemas/IdentifierString'
changedSince:
in: query
name: changed_since
description: 'Most relevant for the /watched endpoint to control the timeframe for changes to DNS or WHOIS fields for watched domains. Example: 2022-02-10T00:00:00Z (ISO-8601)'
schema:
$ref: '#/components/schemas/TimestampFilter'
createDate:
in: query
name: create_date
description: |
Filters domains based on the `create_date` field.
Supports [`>`, `>=`, `<`, `<=`] operators, or no operator for exact matches.
schema:
$ref: '#/components/schemas/DateOperatorsFilter'
createDateWithin:
in: query
name: create_date_within
description: |
Filter domains based on the `create_date` field: the maximum number of days since a domain was first discovered.
schema:
$ref: '#/components/schemas/MaxDaysSince'
datetimeCountsSince:
in: query
name: datetime_counts_since
description: |
Filters counts to include only those generated since the specified ISO-8601 date-time.
This parameter is conditionally required if `include_counts` is set to `true`.
Example: `2022-02-10T00:00:00Z`
schema:
$ref: '#/components/schemas/TimestampFilter'
discoveredBefore:
in: query
name: discovered_before
description: |
Most relevant for the /new endpoint to control the timeframe for when a new domain was discovered. Returns domains discovered before provided date/time. Use with `discovered_since` to return domains discovered in a specific time window.
Example: `2022-02-10T00:00:00Z (ISO-8601)`
schema:
$ref: '#/components/schemas/TimestampFilter'
discoveredSince:
in: query
name: discovered_since
description: |
Most relevant for the /new endpoint to control the timeframe for when a new domain was discovered.
Example: `2022-02-10T00:00:00Z (ISO-8601)`
schema:
$ref: '#/components/schemas/TimestampFilter'
domainsQuery:
in: query
name: domain
description: |
One or more domains (comma-separated) to be investigated.
Example: `example.com,domaintools.com`
schema:
$ref: '#/components/schemas/ApexDomainList'
domainsQueryRequired:
in: query
name: domain
description: |
Required. One or more domains (comma-separated) to be investigated.
Example: `example.com,domaintools.com`
required: true
schema:
$ref: '#/components/schemas/ApexDomainList'
domainState:
in: query
name: domain_state
description: 'Filters domains based on their state.'
schema:
type: string
enum:
- active
- inactive
domainLastIp:
in: query
name: ip
description: IPv4 address the registered domain was last known to point to during an active DNS check.
required: false
schema:
$ref: '#/components/schemas/IPv4Address'
emailAddress:
in: query
name: email
description: Email address from the most recently available WHOIS record, DNS SOA record or SSL certificate.
schema:
$ref: '#/components/schemas/EmailAddress'
emailDomain:
in: query
name: email_domain
description: Only the domain portion of a WHOIS or DNS SOA email address.
schema:
$ref: '#/components/schemas/ApexDomain'
escalatedSince:
in: query
name: escalated_since
description: 'Most relevant for the /watched endpoint to control the timeframe for when a domain was most recently escalated. Example: 2022-02-10T00:00:00Z (ISO-8601)'
schema:
$ref: '#/components/schemas/TimestampFilter'
escalationTypes:
in: query
name: escalation_types
description: "Filters domains based on specific escalation types. Multiple types can be provided."
style: form
explode: true
schema:
$ref: '#/components/schemas/EscalationTypeEnum'
expirationDate:
in: query
name: expiration_date
description: Only include domains expiring on a specific date.
schema:
$ref: '#/components/schemas/DateFilter'
firstSeenSince:
in: query
name: first_seen_since
description: >
Filter domains based on the `first_seen` timestamp.
Returns domains whose `current_lifecycle_first_seen` value is *after* the given datetime.
schema:
$ref: '#/components/schemas/TimestampFilter'
firstSeenWithin:
in: query
name: first_seen_within
description: >
Filter domains based on the `first_seen` field.
Returns only those domains first discovered within the last N seconds.
schema:
$ref: '#/components/schemas/TimeWindowSeconds'
googleAnalytics:
in: query
name: google_analytics
description: Domains with a Google Analytics tracking code
schema:
$ref: '#/components/schemas/IdentifierString'
includeCounts:
in: query
name: include_counts
description: >
If set to `true`, the response will include counts for new, watched, changed, and escalated domains for each monitor.
schema:
$ref: '#/components/schemas/BooleanOptInFlag'
includeDomainData:
in: query
name: include_domain_data
description: 'If set to true, includes additional DNS and WHOIS details in the response.'
schema:
$ref: '#/components/schemas/BooleanOptInFlag'
irisResultsLimit:
in: query
name: limit
description: Specify the maximum number of records to retrieve in an API query. The maximum value is **100**, but this is reduced to **50** if `include_domain_data=true`
schema:
type: integer
maximum: 100
minimum: 1
limitMonitors:
in: query
name: limit
description: |
Specifies the maximum number of monitors to retrieve.
The maximum value is 100, but this may be further restricted if `include_counts=true`.
schema:
type: integer
minimum: 1
maximum: 100
mailserverDomain:
in: query
name: mailserver_domain
description: Only the registered domain portion of the mail server (e.g., `domaintools.net`)
schema:
$ref: '#/components/schemas/ApexDomain'
mailserverHost:
in: query
name: mailserver_host
description: >
Fully-qualified mail server hostname (e.g., mx.domaintools.net).
Performs a Reverse MX lookup to identify domains using this mail server.
schema:
$ref: '#/components/schemas/Fqdn'
mailserverIp:
in: query
name: mailserver_ip
description: IP address of the mail server
schema:
$ref: '#/components/schemas/IPv4Address'
monitorId:
in: query
name: monitor_id
description: Monitor ID from the monitors response - only used when requesting domains for specific monitors.
schema:
type: string
mxExists:
in: query
name: mx_exists
description: Whether domain currently has an MX record in DNS.
schema:
type: boolean
nameserverHost:
in: query
name: nameserver_host
description: Fully-qualified domain name (FQDN) of the name server.
required: false
schema:
$ref: '#/components/schemas/Hostname'
nameserverDomain:
in: query
name: nameserver_domain
description: The registered domain name of the nameserver (e.g., example.com).
required: true
schema:
$ref: '#/components/schemas/Hostname'
nameserverIp:
in: query
name: nameserver_ip
description: The IPv4 address of the name server.
required: true
schema:
$ref: '#/components/schemas/IPv4Address'
notTaggedWithAll:
in: query
name: not_tagged_with_all
description: >
Exclude all domains that are tagged with **all** of the specified tags in the Iris Investigation platform.
This parameter accepts a comma-separated list of tag names.
schema:
$ref: '#/components/schemas/CommaSeparatedTags'
notTaggedWithAny:
in: query
name: not_tagged_with_any
description: >
Exclude all domains that are tagged with **any** of the specified tags in the Iris Investigation platform.
Accepts a comma-separated list of tags.
schema:
$ref: '#/components/schemas/CommaSeparatedTags'
offset:
in: query
name: offset
description: Specifies the starting point for the result set, used for paginating when the number of results exceeds the 'limit'. An offset of 0 starts from the first result.
schema:
type: integer
minimum: 0
order:
in: query
name: order
description: Specifies the sort order for the results, either ascending or descending. Used in conjunction with the 'sort' parameter. Defaults to `desc`.
schema:
type: string
enum:
- asc
- desc
parsedDomainRdapFlag:
name: parsed_domain_rdap
in: query
description: >
If set to `true`, includes the full parsed Domain RDAP record in the response.
schema:
$ref: '#/components/schemas/BooleanOptInFlag'
parsedWhoisFlag:
name: parsed_whois
in: query
description: >
If set to 'true', includes the full parsed WHOIS record in the response.
schema:
$ref: '#/components/schemas/BooleanOptInFlag'
preview:
in: query
name: preview
description: 'Use during API implementation and testing. Will limit results to 10 but not be limited by hourly restrictions.'
required: false
schema:
$ref: '#/components/schemas/BooleanOptInFlag'
registrar:
in: query
name: registrar
description: Exact match to the WHOIS registrar field
schema:
$ref: '#/components/schemas/OrgNameString'
registrant:
in: query
name: registrant
description: Exact match to the WHOIS registrant field
schema:
$ref: '#/components/schemas/OrgNameString'
redirectDomain:
in: query
name: redirect_domain
description: Domains observed to redirect to another domain name.
schema:
$ref: '#/components/schemas/GenericString'
registrantOrg:
in: query
name: registrant_org
description: Exact match to the WHOIS registrant organization field
schema:
$ref: '#/components/schemas/OrgNameString'
responseFormat:
in: query
name: format
description: Specifies the desired response format.
schema:
$ref: '#/components/schemas/ResponseFormat'
resultsPosition:
in: query
name: position
description: >
Cursor for paginated results. Use the value returned in a previous response to retrieve the next page.
required: false
schema:
$ref: '#/components/schemas/PositionToken'
riskScoreRanges:
in: query
name: risk_score_ranges
description: |
Filters domains based on their risk score. Multiple ranges can be selected to broaden the filter. Consult [Domain Risk Scores](https://docs.domaintools.com/riskscore/) for help interpreting scores.
schema:
type: array
items:
type: string
enum:
- '0-0'
- '1-39'
- '40-69'
- '70-99'
- '100-100'
style: form
explode: true
irisContainsSearch:
in: query
name: search
description: Performs a `contains` search.
schema:
$ref: '#/components/schemas/BasicString'
searchHash:
in: query
name: search_hash
description: >
Token returned by the Iris Investigate UI when exporting a search.
Use this value to import and continue an existing search via the API.
schema:
$ref: '#/components/schemas/SearchHashToken'
sortDetect:
in: query
name: sort
description: "Sorts the domain list response. Valid fields to sort by are 'discovered_date', 'changed_date', and 'risk_score'."
schema:
type: array
items:
type: string
enum:
- discovered_date
- changed_date
- risk_score
style: form
explode: true
sortMonitorList:
in: query
name: sort[]
description: Provides options for sorting the monitor list.
schema:
type: string
enum:
- term
- created_date
- domain_counts_changed
- domain_counts_discovered
sslEmail:
in: query
name: ssl_email
description: >
Email address extracted from the SSL certificate associated with a domain.
schema:
$ref: '#/components/schemas/EmailAddress'
sslHash:
in: query
name: ssl_hash
description: >
The SHA-1 hash of an SSL certificate, used to filter for domains associated with a specific certificate.
schema:
$ref: '#/components/schemas/Sha1HexString'
sslOrg:
in: query
name: ssl_org
description: >
Organization name from the SSL certificate. Must be an exact string match.
schema:
$ref: '#/components/schemas/OrgNameString'
sslSubject:
in: query
name: ssl_subject
description: >
Exact match to the Subject distinguished name (DN) string from the SSL certificate.
schema:
$ref: '#/components/schemas/SslSubjectDnString'
taggedWithAll:
in: query
name: tagged_with_all
description: Comma-separated list of tags. Only returns domains tagged with the full list of tags.
schema:
$ref: '#/components/schemas/GenericString'
taggedWithAny:
in: query
name: tagged_with_any
description: Comma-separated list of Iris Investigate tags. Returns domains tagged with any of the tags in a list.
schema:
$ref: '#/components/schemas/GenericString'
tlds:
in: query
name: tlds
description: Filters on specific TLDs
schema:
type: array
items:
type: string
allowReserved: true
style: form
explode: true
topLevelDomain:
in: query
name: tld
description: >
Restrict results to domains under the specified top-level domain (TLD).
schema:
$ref: '#/components/schemas/TopLevelDomain'
websiteTitle:
in: query
name: website_title
description: >
The value of the website’s `<title>` HTML tag. Must be an exact match.
schema:
$ref: '#/components/schemas/WebsiteTitleString'
requestBodies:
Enrich:
description: A request to the Iris Enrich endpoint.
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/EnrichRequestParameters'
Investigate:
description: A request to the Iris Investigate endpoint.
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/InvestigateRequestParameters'
responses:
DetectMonitorSuccess:
description: OK. A list of monitors was successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/MonitorList'
DetectWatchlistOk:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Watchlist'
EnrichSuccess:
description: OK
content:
application/json:
schema:
type: object
properties:
response:
type: object
properties:
limit_exceeded:
type: boolean
message:
type: string
results_count:
type: integer
has_more_results:
type: boolean
results:
type: array
items:
$ref: '#/components/schemas/EnrichResult'
missing_domains:
type: array
items:
$ref: '#/components/schemas/ApexDomain'
InvestigateSuccess:
description: OK
content:
application/json:
schema:
type: object
properties:
response:
type: object
properties:
limit_exceeded:
type: boolean
has_more_results:
type: boolean
message:
type: string
results_count:
type: integer
total_count:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/InvestigateResult'
missing_domains:
type: array
items:
$ref: '#/components/schemas/ApexDomain'
IrisBadRequest:
description: '400: Bad Request. The request was invalid. The response `message` will contain details about the error.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
IrisForbidden:
description: '403: Forbidden. The API credentials provided do not have access to the requested resource or endpoint.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
IrisInternalServerError:
description: '500: Internal Server Error. An unexpected error occurred on the server. If the problem persists, contact DomainTools support.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
IrisNotFound:
description: '404: Not Found. The requested resource does not exist.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
IrisPartialContent:
description: '206: Partial Content. The response is a subset of the full results. The `has_more_results` field in the response will be `true`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
IrisServiceUnavailable:
description: '503: Service Unavailable. The service is temporarily unavailable.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
IrisUnauthorized:
description: '401: Unauthorized. API credentials are required and were not provided, or the provided credentials are not valid.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ApexDomain:
type: string
description: A base (apex) domain like example.com, excluding subdomains. Full validation requires Public Suffix List logic.
minLength: 1
maxLength: 253
pattern: '^(?!\-)(?:[a-zA-Z0-9-]{1,63}\.)+[a-zA-Z]{2,63}$'
ApexDomainList:
type: string
pattern: '^([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(,([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,})*$'
description: A comma-separated list of one or more apex domains to investigate.
BasicString:
type: string
minLength: 1
maxLength: 255
description: A non-empty string with a standard length limit.
BooleanOptInFlag:
type: boolean
description: >
An optional boolean flag that enables a specific feature or response extension when set to `true`.
If `false` or omitted, the feature is ignored.
CommaSeparatedTags:
type: string
description: >
A comma-separated list of tag names.
Tags are matched exactly and compared case-insensitively
unless otherwise specified.
maxLength: 512
DateFilter:
type: string
format: date
description: >
A calendar date in the format YYYY-MM-DD, per RFC 3339 (full-date).
Does not include a time or timezone.
DateOperatorsFilter:
type: string
description: |
A date in YYYY-MM-DD format, optionally prefixed with an operator (`>`, `>=`, `<`, `<=`) for comparison.
Example: `<=2025-01-01`
pattern: '^(>|>=|<|<=)?\d{4}-\d{2}-\d{2}$'
DetectDomain:
type: object
properties:
state:
type: string
domain:
type: string
status:
type: string
enum: [active, inactive]
discovered_date:
type: string
format: date-time
changed_date:
type: string
format: date-time
risk_score:
type: integer
risk_score_status:
description: "Indicates if the risk score is 'provisional' (initial calculation) or full."
type: string
risk_score_components:
$ref: '#/components/schemas/DetectRiskComponents'
mx_exists:
type: boolean
tld:
type: string
id:
type: string
escalations:
type: array
items:
$ref: '#/components/schemas/DetectEscalation'
monitor_ids:
type: array
items:
type: string
name_server:
type: array
items:
type: object
properties:
host: { type: string }
registrant_contact_email:
type: array
items:
type: string
registrar:
type: string
create_date:
type: integer
description: "Domain creation date in YYYYMMDD format."
ip:
type: array
items:
type: object
properties:
country_code: { type: string }
ip: { type: string }
isp: { type: string }
mx:
type: array
items:
type: object
properties:
host: { type: string }
DetectDomainList:
type: object
properties:
watchlist_domains:
type: array
items:
$ref: '#/components/schemas/DetectDomain'
total_count:
type: integer
count:
type: integer
offset:
type: integer
limit:
type: integer
DetectEscalation:
type: object
properties:
escalation_type:
$ref: '#/components/schemas/EscalationTypeEnum'
id:
type: string
created:
type: string
format: date-time
created_by:
type: string
DetectRiskComponents:
type: object
properties:
proximity:
type: integer
threat_profile:
$ref: '#/components/schemas/DetectThreatProfile'
DetectThreatProfile:
type: object
properties:
phishing:
type: integer
malware:
type: integer
spam:
type: integer
EmailAddress:
type: string
format: email
maxLength: 254
description: >
A valid email address, as defined by RFC 5322 and commonly used in WHOIS, SSL certificates, RDAP records, or domain registration contacts.
ErrorResponse:
type: object
properties:
error:
type: string
message:
type: string
Escalations:
type: object
properties:
watchlist_domains:
type: array
items:
type: object
properties:
state:
type: string
domain:
type: string
discovered_date:
type: string
changed_date:
type: string
id:
type: string
assigned_by:
type: string
assigned_date:
type: string
EscalationTypeEnum:
type: string
description: The type of escalation action.
enum:
- blocked
- google_safe
Fqdn:
type: string
format: hostname
description: >
A Fully Qualified Domain Name (FQDN), including subdomains (e.g., www.example.com).
Must be a valid DNS hostname per RFC 1123, excluding trailing dot.
minLength: 1
maxLength: 253
pattern: '^(?=.{1,253}$)(?:(?!-)[a-zA-Z0-9-]{1,63}(?<!-)\.)+[a-zA-Z]{2,63}$'
GenericString:
type: string
description: A generic and unconstrained string value.
Hostname:
type: string
format: hostname
description: A valid, fully-qualified domain name (FQDN).
minLength: 3
maxLength: 253
IdentifierString:
type: string
minLength: 1
maxLength: 128
description: A short identifier, code, or handle.
IPv4Address:
type: string
format: ipv4
description: A standard IPv4 address.
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.){3}(25[0-5]|(2[0-4]|1\d|[1-9]|)\d)$'
MaxDaysSince:
type: integer
minimum: 1
description: A positive integer representing the maximum number of days.
OrgNameString:
type: string
minLength: 1
maxLength: 256
pattern: "^[\\p{L}\\p{N} .,\\-&()'/\"]+$"
description: >
A human-readable organization name as used in WHOIS or RDAP records, such as a registrar, registrant, or sponsoring organization.
Supports Unicode letters and numbers, along with common punctuation.
PositionToken:
type: string
description: |
An opaque string token used for cursor-based pagination.
Returned in the `position` field of a paginated response when `has_more_results` is true, and used as a query parameter to retrieve the next result set.
Example: `2c056abadfb64b67ba18896af2c5b900`
ResponseFormat:
type: string
enum:
- html
- json
- xml
description: |
The desired response format. Acceptable values are:
- `json`: Machine-readable JSON
- `xml`: XML-encoded data
- `html`: Human-readable HTML page
RiskScoreValue:
type: integer
minimum: 0
maximum: 99
SearchHashToken:
type: string
description: |
Opaque token representing a saved search from the Iris Investigate UI.
Exported via “Search → Export” in the Iris UI.
Example: `aGVsbG93b3JsZF9zZWFyY2hfaGFzaF9jb2Rlcw==`
Sha1HexString:
type: string
description: >
A 40-character hexadecimal SHA-1 hash string, typically used to identify SSL certificates or digital signatures.
pattern: '^[a-fA-F0-9]{40}$'
SslSubjectDnString:
type: string
minLength: 1
maxLength: 1024
description: |
A distinguished name (DN) string representing the Subject field of an SSL certificate.
Typically includes components like CN, O, C, ST, and L in a comma-separated format.
Example: `C=US, ST=California, L=San Francisco, O=Example Corp, CN=example.com`
TimestampFilter:
type: string
format: date-time
description: >
An RFC 3339-compliant timestamp (e.g., `2025-01-01T00:00:00Z`)
used to filter results by datetime thresholds.
TimeWindowSeconds:
type: integer
format: int64
minimum: 1
description: >
A positive integer representing a time window, in seconds.
Used to filter results based on how recently an event occurred.
TopLevelDomain:
type: string
minLength: 2
maxLength: 128
pattern: '^[a-z]{2,63}(\.[a-z]{2,63})*$'
description: >
A top-level or public suffix domain, such as `com`, `org`, or `co.uk`. Must not include a leading dot.
WebsiteTitleString:
type: string
minLength: 1
maxLength: 512
description: >
The exact value of the `<title>` tag from a website's HTML.
DomainProfileTemplate:
type: object
description: A comprehensive template defining the complete structure of a domain profile. Specific data types are defined in inheriting schemas.
properties:
domain:
type: string
whois_url:
type: string
adsense: {}
alexa:
type: integer
popularity_rank:
type: number
active:
type: boolean
google_analytics: {}
ga4:
type: array
items: {}
gtm_codes:
type: array
items: {}
fb_codes:
type: array
items: {}
hotjar_codes:
type: array
items: {}
baidu_codes:
type: array
items: {}
yandex_codes:
type: array
items: {}
matomo_codes:
type: array
items: {}
statcounter_project_codes:
type: array
items: {}
statcounter_security_codes:
type: array
items: {}
admin_contact:
$ref: '#/components/schemas/BaseContact'
billing_contact:
$ref: '#/components/schemas/BaseContact'
registrant_contact:
$ref: '#/components/schemas/BaseContact'
technical_contact:
$ref: '#/components/schemas/BaseContact'
create_date: {}
expiration_date: {}
email_domain:
type: array
items: {}
soa_email:
type: array
items: {}
ssl_email:
type: array
items: {}
additional_whois_email:
type: array
items: {}
ip:
type: array
items:
type: object
properties:
address: {}
asn:
type: array
items: {}
country_code: {}
isp: {}
mx:
type: array
items:
type: object
properties:
host: {}
domain: {}
ip:
type: array
items: {}
priority:
type: number
name_server:
type: array
items:
type: object
properties:
host: {}
domain: {}
ip:
type: array
items: {}
domain_risk:
$ref: '#/components/schemas/DomainRisk'
redirect: {}
redirect_domain: {}
registrant_name: {}
registrant_org: {}
registrar: {}
registrar_status:
type: array
items:
type: string
spf_info:
type: string
ssl_info:
type: array
items:
$ref: '#/components/schemas/BaseSslInfo'
tld:
type: string
website_response:
type: number
data_updated_timestamp:
$ref: '#/components/schemas/TimestampFilter'
website_title: {}
server_type: {}
first_seen: {}
tags:
type: array
items:
type: object
properties:
label:
type: string
scope:
type: string
tagged_at:
type: string
parsed_whois:
$ref: '#/components/schemas/ParsedWhois'
parsed_domain_rdap:
$ref: '#/components/schemas/ParsedDomainRdap'
BaseContact:
type: object
description: A template for contact information blocks.
properties:
name: {}
org: {}
street: {}
city: {}
state: {}
postal: {}
country: {}
phone: {}
fax: {}
email:
type: array
items: {}
BaseSslInfo:
type: object
description: A template for SSL certificate information blocks.
properties:
hash: {}
subject: {}
organization: {}
email:
type: array
items:
type: string
alt_names:
type: array
items: {}
sources:
type: object
properties:
active:
type: integer
passive:
type: integer
common_name: {}
issuer_common_name: {}
not_after: {}
not_before: {}
duration: {}
DomainRisk:
type: object
properties:
risk_score:
$ref: '#/components/schemas/RiskScoreValue'
components:
type: array
description: A list of risk components and their individual scores that contribute to the overall domain risk.
items:
$ref: '#/components/schemas/DomainRiskComponent'
DomainRiskComponent:
description: A polymorphic schema representing one of several types of risk components.
oneOf:
- $ref: '#/components/schemas/Proximity'
- $ref: '#/components/schemas/ThreatProfile'
- $ref: '#/components/schemas/ThreatProfileMalware'
- $ref: '#/components/schemas/ThreatProfilePhishing'
- $ref: '#/components/schemas/ThreatProfileSpam'
- $ref: '#/components/schemas/ZeroListedScore'
discriminator:
propertyName: name
mapping:
proximity: '#/components/schemas/Proximity'
threat_profile: '#/components/schemas/ThreatProfile'
threat_profile_malware: '#/components/schemas/ThreatProfileMalware'
threat_profile_phishing: '#/components/schemas/ThreatProfilePhishing'
threat_profile_spam: '#/components/schemas/ThreatProfileSpam'
zerolist: '#/components/schemas/ZeroListedScore'
EnrichValue:
type: object
properties:
value:
type: string
EnrichTracker:
type: object
description: A tracker identifier.
properties:
value:
$ref: '#/components/schemas/IdentifierString'
EnrichRequestParameters:
type: object
required:
- domain
properties:
domain:
$ref: '#/components/parameters/domainsQueryRequired/schema'
app_partner:
$ref: '#/components/parameters/appPartner/schema'
app_name:
$ref: '#/components/parameters/appName/schema'
app_version:
$ref: '#/components/parameters/appVersion/schema'
format:
$ref: '#/components/parameters/responseFormat/schema'
parsed_whois:
$ref: '#/components/parameters/parsedWhoisFlag/schema'
parsed_domain_rdap:
$ref: '#/components/parameters/parsedDomainRdapFlag/schema'
EnrichResult:
allOf:
- $ref: '#/components/schemas/DomainProfileTemplate'
properties:
adsense:
$ref: '#/components/schemas/EnrichTracker'
google_analytics:
$ref: '#/components/schemas/EnrichTracker'
ga4:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
gtm_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
fb_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
hotjar_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
baidu_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
yandex_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
matomo_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
statcounter_project_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
statcounter_security_codes:
type: array
items:
$ref: '#/components/schemas/EnrichTracker'
admin_contact:
$ref: '#/components/schemas/EnrichContact'
billing_contact:
$ref: '#/components/schemas/EnrichContact'
registrant_contact:
$ref: '#/components/schemas/EnrichContact'
technical_contact:
$ref: '#/components/schemas/EnrichContact'
create_date:
$ref: '#/components/schemas/EnrichValue'
expiration_date:
$ref: '#/components/schemas/EnrichValue'
email_domain:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
soa_email:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
ssl_email:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
additional_whois_email:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
ip:
type: array
items:
type: object
properties:
address:
$ref: '#/components/schemas/EnrichValue'
asn:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
country_code:
$ref: '#/components/schemas/EnrichValue'
isp:
$ref: '#/components/schemas/EnrichValue'
mx:
type: array
items:
type: object
properties:
host:
$ref: '#/components/schemas/EnrichValue'
domain:
$ref: '#/components/schemas/EnrichValue'
ip:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
priority:
type: number
name_server:
type: array
items:
type: object
properties:
host:
$ref: '#/components/schemas/EnrichValue'
domain:
$ref: '#/components/schemas/EnrichValue'
ip:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
redirect:
$ref: '#/components/schemas/EnrichValue'
redirect_domain:
$ref: '#/components/schemas/EnrichValue'
registrant_name:
$ref: '#/components/schemas/EnrichValue'
registrant_org:
$ref: '#/components/schemas/EnrichValue'
registrar:
$ref: '#/components/schemas/EnrichValue'
server_type:
$ref: '#/components/schemas/EnrichValue'
first_seen:
$ref: '#/components/schemas/EnrichValue'
website_title:
$ref: '#/components/schemas/EnrichValue'
ssl_info:
type: array
items:
allOf:
- $ref: '#/components/schemas/BaseSslInfo'
properties:
hash:
$ref: '#/components/schemas/EnrichValue'
subject:
$ref: '#/components/schemas/EnrichValue'
organization:
$ref: '#/components/schemas/EnrichValue'
alt_names:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
common_name:
$ref: '#/components/schemas/EnrichValue'
issuer_common_name:
$ref: '#/components/schemas/EnrichValue'
not_after:
type: integer
not_before:
type: integer
duration:
type: integer
EnrichContact:
allOf:
- $ref: '#/components/schemas/BaseContact'
properties:
name:
$ref: '#/components/schemas/EnrichValue'
org:
$ref: '#/components/schemas/EnrichValue'
street:
$ref: '#/components/schemas/EnrichValue'
city:
$ref: '#/components/schemas/EnrichValue'
state:
$ref: '#/components/schemas/EnrichValue'
postal:
$ref: '#/components/schemas/EnrichValue'
country:
$ref: '#/components/schemas/EnrichValue'
phone:
$ref: '#/components/schemas/EnrichValue'
fax:
$ref: '#/components/schemas/EnrichValue'
email:
type: array
items:
$ref: '#/components/schemas/EnrichValue'
PivotedValue:
type: object
properties:
value:
type: string
count:
type: integer
format: int64
description: The number of other domains that share this exact value.
PivotedTracker:
type: object
description: A tracker identifier and its associated pivot count.
properties:
value:
$ref: '#/components/schemas/IdentifierString'
count:
type: integer
format: int64
description: The number of other domains that share this exact value.
InvestigateResult:
allOf:
- $ref: '#/components/schemas/DomainProfileTemplate'
properties:
adsense:
$ref: '#/components/schemas/PivotedTracker'
google_analytics:
$ref: '#/components/schemas/PivotedTracker'
ga4:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
gtm_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
fb_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
hotjar_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
baidu_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
yandex_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
matomo_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
statcounter_project_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
statcounter_security_codes:
type: array
items:
$ref: '#/components/schemas/PivotedTracker'
admin_contact:
$ref: '#/components/schemas/PivotedContact'
billing_contact:
$ref: '#/components/schemas/PivotedContact'
registrant_contact:
$ref: '#/components/schemas/PivotedContact'
technical_contact:
$ref: '#/components/schemas/PivotedContact'
create_date:
$ref: '#/components/schemas/PivotedValue'
expiration_date:
$ref: '#/components/schemas/PivotedValue'
email_domain:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
soa_email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
ssl_email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
additional_whois_email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
ip:
type: array
items:
type: object
properties:
address:
$ref: '#/components/schemas/PivotedValue'
asn:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
country_code:
$ref: '#/components/schemas/PivotedValue'
isp:
$ref: '#/components/schemas/PivotedValue'
mx:
type: array
items:
type: object
properties:
host:
$ref: '#/components/schemas/PivotedValue'
domain:
$ref: '#/components/schemas/PivotedValue'
ip:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
priority:
type: number
name_server:
type: array
items:
type: object
properties:
host:
$ref: '#/components/schemas/PivotedValue'
domain:
$ref: '#/components/schemas/PivotedValue'
ip:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
redirect:
$ref: '#/components/schemas/PivotedValue'
redirect_domain:
$ref: '#/components/schemas/PivotedValue'
registrant_name:
$ref: '#/components/schemas/PivotedValue'
registrant_org:
$ref: '#/components/schemas/PivotedValue'
registrar:
$ref: '#/components/schemas/PivotedValue'
server_type:
$ref: '#/components/schemas/PivotedValue'
first_seen:
$ref: '#/components/schemas/PivotedValue'
website_title:
$ref: '#/components/schemas/PivotedValue'
ssl_info:
type: array
items:
allOf:
- $ref: '#/components/schemas/BaseSslInfo'
properties:
hash:
$ref: '#/components/schemas/PivotedValue'
subject:
$ref: '#/components/schemas/PivotedValue'
organization:
$ref: '#/components/schemas/PivotedValue'
alt_names:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
common_name:
$ref: '#/components/schemas/PivotedValue'
issuer_common_name:
$ref: '#/components/schemas/PivotedValue'
not_after:
$ref: '#/components/schemas/PivotedValue'
not_before:
$ref: '#/components/schemas/PivotedValue'
duration:
$ref: '#/components/schemas/PivotedValue'
Monitor:
type: object
description: Details of a single Iris Detect monitor.
properties:
term:
type: string
match_substring_variations:
type: boolean
nameserver_exclusions:
type: array
items:
type: string
text_exclusions:
type: array
items:
type: string
id:
type: string
created_date:
type: string
format: date-time
updated_date:
type: string
format: date-time
state:
type: string
enum:
- active
- inactive
status:
type: string
domain_counts:
$ref: '#/components/schemas/MonitorDomainCounts'
created_by:
type: string
MonitorDomainCounts:
type: object
description: Counts of domains associated with a monitor in various states.
properties:
new:
type: integer
description: The number of new domains discovered.
watched:
type: integer
description: The number of domains currently on the watchlist.
escalated:
type: integer
description: The number of domains that have been escalated.
changed:
type: integer
description: The number of watched domains that have changed.
MonitorList:
type: object
description: A list of Iris Detect monitors and associated metadata.
properties:
total_count:
type: integer
offset:
type: integer
limit:
type: integer
monitors:
type: array
items:
$ref: '#/components/schemas/Monitor'
PivotedContact:
allOf:
- $ref: '#/components/schemas/BaseContact'
properties:
name:
$ref: '#/components/schemas/PivotedValue'
org:
$ref: '#/components/schemas/PivotedValue'
street:
$ref: '#/components/schemas/PivotedValue'
city:
$ref: '#/components/schemas/PivotedValue'
state:
$ref: '#/components/schemas/PivotedValue'
postal:
$ref: '#/components/schemas/PivotedValue'
country:
$ref: '#/components/schemas/PivotedValue'
phone:
$ref: '#/components/schemas/PivotedValue'
fax:
$ref: '#/components/schemas/PivotedValue'
email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
InvestigateRequestParameters:
type: object
properties:
domain:
$ref: '#/components/parameters/domainsQuery/schema'
ip:
$ref: '#/components/parameters/domainLastIp/schema'
email:
$ref: '#/components/parameters/emailAddress/schema'
email_domain:
$ref: '#/components/parameters/emailDomain/schema'
nameserver_host:
$ref: '#/components/parameters/nameserverHost/schema'
nameserver_domain:
$ref: '#/components/parameters/nameserverDomain/schema'
nameserver_ip:
$ref: '#/components/parameters/nameserverIp/schema'
registrar:
$ref: '#/components/parameters/registrar/schema'
registrant:
$ref: '#/components/parameters/registrant/schema'
registrant_org:
$ref: '#/components/parameters/registrantOrg/schema'
mailserver_host:
$ref: '#/components/parameters/mailserverHost/schema'
tagged_with_any:
$ref: '#/components/parameters/taggedWithAny/schema'
tagged_with_all:
$ref: '#/components/parameters/taggedWithAll/schema'
mailserver_domain:
$ref: '#/components/parameters/mailserverDomain/schema'
mailserver_ip:
$ref: '#/components/parameters/mailserverIp/schema'
redirect_domain:
$ref: '#/components/parameters/redirectDomain/schema'
ssl_hash:
$ref: '#/components/parameters/sslHash/schema'
ssl_org:
$ref: '#/components/parameters/sslOrg/schema'
ssl_subject:
$ref: '#/components/parameters/sslSubject/schema'
ssl_email:
$ref: '#/components/parameters/sslEmail/schema'
google_analytics:
$ref: '#/components/parameters/googleAnalytics/schema'
adsense:
$ref: '#/components/parameters/adsense/schema'
search_hash:
$ref: '#/components/parameters/searchHash/schema'
position:
$ref: '#/components/parameters/resultsPosition/schema'
active:
$ref: '#/components/parameters/active/schema'
tld:
$ref: '#/components/parameters/topLevelDomain/schema'
create_date:
$ref: '#/components/parameters/createDate/schema'
create_date_within:
$ref: '#/components/parameters/createDateWithin/schema'
first_seen_within:
$ref: '#/components/parameters/firstSeenWithin/schema'
first_seen_since:
$ref: '#/components/parameters/firstSeenSince/schema'
expiration_date:
$ref: '#/components/parameters/expirationDate/schema'
website_title:
$ref: '#/components/parameters/websiteTitle/schema'
not_tagged_with_any:
$ref: '#/components/parameters/notTaggedWithAny/schema'
not_tagged_with_all:
$ref: '#/components/parameters/notTaggedWithAll/schema'
app_partner:
$ref: '#/components/parameters/appPartner/schema'
app_name:
$ref: '#/components/parameters/appName/schema'
app_version:
$ref: '#/components/parameters/appVersion/schema'
format:
$ref: '#/components/parameters/responseFormat/schema'
ParsedDomainRdap:
type: object
description: Parsed data from the domain's RDAP record. Present only when the request includes `parsed_domain_rdap=true`.
properties:
registrant_contact:
$ref: '#/components/schemas/RdapContact'
admin_contact:
$ref: '#/components/schemas/RdapContact'
technical_contact:
$ref: '#/components/schemas/RdapContact'
registrant_name:
$ref: '#/components/schemas/PivotedValue'
registrar_iana_id:
$ref: '#/components/schemas/PivotedValue'
additional_whois_email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
registrar:
$ref: '#/components/schemas/PivotedValue'
create_date:
$ref: '#/components/schemas/PivotedValue'
expiration_date:
$ref: '#/components/schemas/PivotedValue'
registrar_status:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
email_domain:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
ParsedWhois:
type: object
description: Parsed data from the domain's WHOIS record. Present only when the request includes `parsed_whois=true`.
properties:
technical_contact:
$ref: '#/components/schemas/WhoisContact'
registrant_contact:
$ref: '#/components/schemas/WhoisContact'
admin_contact:
$ref: '#/components/schemas/WhoisContact'
additional_whois_email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
registrar:
$ref: '#/components/schemas/PivotedValue'
create_date:
$ref: '#/components/schemas/PivotedValue'
expiration_date:
$ref: '#/components/schemas/PivotedValue'
registrant_name:
$ref: '#/components/schemas/PivotedValue'
registrant_org:
$ref: '#/components/schemas/PivotedValue'
registrar_status:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
Proximity:
type: object
required:
- name
- risk_score
properties:
name:
type: string
description: The type of risk component.
enum: [proximity]
risk_score:
$ref: '#/components/schemas/RiskScoreValue'
RdapContact:
type: object
description: Contact details from an RDAP record.
properties:
name:
$ref: '#/components/schemas/PivotedValue'
org:
$ref: '#/components/schemas/PivotedValue'
street:
$ref: '#/components/schemas/PivotedValue'
city:
$ref: '#/components/schemas/PivotedValue'
state:
$ref: '#/components/schemas/PivotedValue'
postal:
$ref: '#/components/schemas/PivotedValue'
country:
$ref: '#/components/schemas/PivotedValue'
phone:
$ref: '#/components/schemas/PivotedValue'
fax:
$ref: '#/components/schemas/PivotedValue'
email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
ThreatProfile:
type: object
required:
- name
- risk_score
properties:
name:
type: string
description: The type of risk component.
enum: [threat_profile]
risk_score:
$ref: '#/components/schemas/RiskScoreValue'
description: Indicates risk based on machine-learning models.
ThreatProfileMalware:
type: object
required:
- name
- risk_score
properties:
name:
type: string
description: The type of risk component.
enum: [threat_profile_malware]
risk_score:
$ref: '#/components/schemas/RiskScoreValue'
description: Indicates risk based on a machine-learning model that classifies domains as malware-related.
ThreatProfilePhishing:
type: object
required:
- name
- risk_score
properties:
name:
type: string
description: The type of risk component.
enum: [threat_profile_phishing]
risk_score:
$ref: '#/components/schemas/RiskScoreValue'
description: Indicates risk based on a machine-learning model that classifies domains as phishing-related.
ThreatProfileSpam:
type: object
required:
- name
- risk_score
properties:
name:
type: string
description: The type of risk component.
enum: [threat_profile_spam]
risk_score:
$ref: '#/components/schemas/RiskScoreValue'
description: Indicates risk based on a machine-learning model that classifies domains as spam-related.
Watchlist:
type: object
properties:
watchlist_domains:
type: array
items:
type: object
properties:
state:
type: string
enum:
- watched
- ignored
domain:
type: string
discovered_date:
type: string
changed_date:
type: string
id:
type: string
assigned_by:
type: string
assigned_date:
type: string
WatchlistBase:
type: object
properties:
watchlist_domain_ids:
type: array
items:
type: string
app_partner:
$ref: '#/components/parameters/appPartner'
app_name:
$ref: '#/components/parameters/appName'
app_version:
$ref: '#/components/parameters/appVersion'
WatchlistState:
allOf:
- $ref: '#/components/schemas/WatchlistBase'
- type: object
properties:
state:
type: string
enum:
- watched
- ignored
WatchlistEscalation:
allOf:
- $ref: '#/components/schemas/WatchlistBase'
- type: object
properties:
escalation_type:
$ref: '#/components/schemas/EscalationTypeEnum'
WhoisContact:
type: object
description: Contact details from a WHOIS record.
properties:
name:
$ref: '#/components/schemas/PivotedValue'
org:
$ref: '#/components/schemas/PivotedValue'
street:
$ref: '#/components/schemas/PivotedValue'
city:
$ref: '#/components/schemas/PivotedValue'
state:
$ref: '#/components/schemas/PivotedValue'
postal:
$ref: '#/components/schemas/PivotedValue'
country:
$ref: '#/components/schemas/PivotedValue'
phone:
$ref: '#/components/schemas/PivotedValue'
fax:
$ref: '#/components/schemas/PivotedValue'
email:
type: array
items:
$ref: '#/components/schemas/PivotedValue'
ZeroListedScore:
type: object
required:
- name
- risk_score
properties:
name:
type: string
description: The type of risk component.
enum: [zerolist]
risk_score:
type: integer
description: The risk score for a zerolisted domain, which is always 0.
enum: [0]
description: Indicates the domain is on a known-good 'zero list' and is not considered a threat.
securitySchemes:
hmac_auth:
type: apiKey
in: query
name: signature
description: |
A secure scheme using a Hashed Message Authentication Code (HMAC).
This method requires three query parameters to be sent with the request:
1. `api_username`: Your API username.
2. `timestamp`: The current timestamp in ISO 8601 format (e.g., `2020-02-01T22:37:59Z`).
3. `signature`: The HMAC signature of the request. This is a hash (SHA-256 recommended) of your username, the timestamp, and the request URI, signed with your secret API key.
header_auth:
type: apiKey
in: header
name: X-Api-Key
description: |
A secure authentication method where the API key is provided in the `X-Api-Key` HTTP request header.
open_key_auth:
type: http
scheme: basic
description: |
A simple authentication scheme using your `api_username` as the username and your `api_key` as the password. We strongly recommend using HMAC or Header authentication instead to avoid exposing your credentials in the URL.