diff --git a/domaintools/specs/iris-openapi.yaml b/domaintools/specs/iris-openapi.yaml index f2dddb8..94d9cf7 100644 --- a/domaintools/specs/iris-openapi.yaml +++ b/domaintools/specs/iris-openapi.yaml @@ -4,9 +4,16 @@ info: version: 1.0.0 description: | The OpenAPI spec for DomainTools Iris endpoints. + contact: + name: DomainTools Support + url: https://www.domaintools.com/support + email: enterprisesupport@domaintools.com + license: + name: MIT + termsOfService: https://www.domaintools.com/company/terms-of-service/ servers: - - url: https://api.domaintools.com - description: DomainTools APIs + - description: DomainTools APIs + url: https://api.domaintools.com security: - header_auth: [] - open_key_auth: [] @@ -50,6 +57,8 @@ paths: $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/DetectUnprocessableEntity' externalDocs: url: https://docs.domaintools.com/api/iris/detect/reference/#add-remove-from-watchlist /v1/iris-detect/domains/ignored/: @@ -205,6 +214,8 @@ paths: $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/DetectUnprocessableEntity' externalDocs: url: https://docs.domaintools.com/api/iris/detect/reference/#escalate /v1/iris-detect/monitors/: @@ -236,6 +247,109 @@ paths: $ref: '#/components/responses/NotFound' externalDocs: url: https://docs.domaintools.com/api/iris/detect/reference/#monitor-list + post: + operationId: postDetectMonitor + summary: Create a new monitor to track lookalike domains for a specific term. + description: | + Creates a monitor that begins discovering matching domains immediately. + The monitor `status` is `pending` after creation and changes to `completed` + once initial domain discovery finishes. + + Requires the "manage monitors" permission. + tags: + - Iris Detect + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateMonitorRequest' + responses: + '200': + description: Monitor created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/CreateMonitorResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/DetectUnprocessableEntity' + externalDocs: + url: https://docs.domaintools.com/api/iris/detect/guide/#create-monitor + put: + operationId: putDetectMonitor + summary: Update the configuration of an existing monitor. + description: | + Modifies match settings and exclusions for an existing monitor. + Include only the fields you want to change; omitted fields retain their current values. + + A recently created monitor may not be immediately available for updates. + Wait until the monitor's `status` changes from `pending` to `completed` + before sending update requests. + + Requires the "manage monitors" permission. + tags: + - Iris Detect + parameters: + - $ref: '#/components/parameters/monitorIdRequired' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateMonitorRequest' + responses: + '200': + description: Monitor updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateMonitorResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/DetectUnprocessableEntity' + externalDocs: + url: https://docs.domaintools.com/api/iris/detect/guide/#update-monitor + delete: + operationId: deleteDetectMonitor + summary: Permanently delete a monitor and stop tracking its associated domains. + description: | + Deletes the specified monitor. This action is permanent and can't be undone. + + Requires the "manage monitors" permission. + tags: + - Iris Detect + parameters: + - $ref: '#/components/parameters/monitorIdRequired' + responses: + '200': + description: Monitor deleted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteMonitorResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + externalDocs: + url: https://docs.domaintools.com/api/iris/detect/guide/#delete-monitor /v1/iris-enrich/: get: operationId: getIrisEnrich @@ -345,6 +459,7 @@ paths: - $ref: '#/components/parameters/sslHash' - $ref: '#/components/parameters/sslOrg' - $ref: '#/components/parameters/sslSubject' + - $ref: '#/components/parameters/sslIssuerCommonName' - $ref: '#/components/parameters/statCounterProjectCode' - $ref: '#/components/parameters/statCounterSecurityCode' - $ref: '#/components/parameters/taggedWithAll' @@ -359,8 +474,13 @@ paths: - $ref: '#/components/parameters/expirationDate' - $ref: '#/components/parameters/firstSeenSince' - $ref: '#/components/parameters/firstSeenWithin' + - $ref: '#/components/parameters/ipCountryCode' - $ref: '#/components/parameters/notTaggedWithAll' - $ref: '#/components/parameters/notTaggedWithAny' + - $ref: '#/components/parameters/rank' + - $ref: '#/components/parameters/riskScore' + - $ref: '#/components/parameters/sslNotAfter' + - $ref: '#/components/parameters/sslNotBefore' - $ref: '#/components/parameters/topLevelDomain' - $ref: '#/components/parameters/parsedDomainRdapFlag' - $ref: '#/components/parameters/parsedWhoisFlag' @@ -391,13 +511,21 @@ paths: '503': $ref: '#/components/responses/ServiceUnavailable' externalDocs: - url: https://docs.domaintools.com/api/iris/investigate/ + url: https://docs.domaintools.com/api/iris/ post: operationId: postIrisInvestigate summary: Returns data from a POST request. tags: - Iris Investigate - description: The GET method is available for simple queries. + description: | + The GET method is available for simple queries. + + The POST method supports two request formats: + + - **Form parameters** (application/x-www-form-urlencoded): Traditional parameter-based searches + - **IrisQL** (text/plain): Complex queries using IrisQL query language for advanced filtering and OR logic + + For IrisQL usage and syntax, see the [IrisQL API Guide](https://docs.domaintools.com/api/iris/investigate/irisql/). requestBody: $ref: '#/components/requestBodies/Investigate' responses: @@ -418,7 +546,7 @@ paths: '503': $ref: '#/components/responses/ServiceUnavailable' externalDocs: - url: https://docs.domaintools.com/api/iris/investigate/ + url: https://docs.domaintools.com/api/iris/ /v1/account/: get: operationId: getAccountInfo @@ -704,6 +832,51 @@ components: Returns only those domains first discovered within the last N seconds. schema: $ref: '#/components/schemas/TimeWindowSeconds' + ipCountryCode: + in: query + name: ip_country_code + description: | + Search filter parameter. + Country code for IP A-record. + schema: + type: string + pattern: ^[A-Z]{2}$ + description: Two-letter ISO country code (uppercase) + rank: + in: query + name: rank + description: | + Search filter parameter. + Popularity rank (replaces Alexa ranking). + schema: + type: integer + minimum: 1 + riskScore: + in: query + name: risk_score + description: | + Search filter parameter. + Domain Risk Score. See [Domain Risk Scores](https://docs.domaintools.com/riskscore/). + schema: + type: integer + minimum: 0 + maximum: 100 + sslNotAfter: + in: query + name: ssl_not_after + description: | + Search filter parameter. + Validity end date for a certificate (YYYY-MM-DD). + schema: + $ref: '#/components/schemas/DateFilter' + sslNotBefore: + in: query + name: ssl_not_before + description: | + Search filter parameter. + Validity begin date for a certificate (YYYY-MM-DD). + schema: + $ref: '#/components/schemas/DateFilter' googleAnalyticsCode: in: query name: google_analytics @@ -714,7 +887,7 @@ components: $ref: '#/components/schemas/IdentifierString' googleAnalytics4Code: in: query - name: google_analytics_4 + name: ga4 description: | Base search parameter. Domains with a Google Analytics tracking code. @@ -773,11 +946,11 @@ components: 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`. + The default is 500. The maximum is restricted to 100 if `include_counts=true`. schema: type: integer minimum: 1 - maximum: 100 + maximum: 500 mailserverDomain: in: query name: mailserver_domain @@ -817,6 +990,15 @@ components: description: Monitor ID from the monitors response - only used when requesting domains for specific monitors. schema: type: string + monitorIdRequired: + in: query + name: monitor_id + required: true + description: | + The ID of the monitor to operate on. + Retrieve monitor IDs from the monitor list endpoint (`GET /v1/iris-detect/monitors/`). + schema: + type: string mxExists: in: query name: mx_exists @@ -884,7 +1066,7 @@ components: preview: in: query name: preview - description: Use during API implementation and testing. Will limit results to 10 but not be limited by hourly restrictions. + description: Use during API implementation and testing. Will limit results to 2 but not be limited by hourly restrictions. Use for development and testing only. Sustained usage violates Terms of Service and can result in service suspension. required: false schema: $ref: '#/components/schemas/BooleanOptInFlag' @@ -936,7 +1118,7 @@ components: required: false schema: $ref: '#/components/schemas/PositionToken' - dzzzzzzz: + resultsSortBy: in: query name: sort_by description: | @@ -1081,6 +1263,14 @@ components: Exact match to the Subject distinguished name (DN) string from the SSL certificate. schema: $ref: '#/components/schemas/SslSubjectDnString' + sslIssuerCommonName: + in: query + name: ssl_issuer_common_name + description: | + Base search parameter. + Certificate issuer Common Name. + schema: + $ref: '#/components/schemas/GenericString' statCounterProjectCode: in: query name: statcounter_project @@ -1180,12 +1370,31 @@ components: schema: $ref: '#/components/schemas/EnrichRequestParameters' Investigate: - description: A request to the Iris Investigate endpoint. + description: | + A request to the Iris Investigate endpoint. + + Supports two request formats: + + - **Form parameters** (application/x-www-form-urlencoded): Standard parameter-based search + - **IrisQL** (text/plain): IrisQL query language for complex searches with OR logic + + For IrisQL usage, see the [IrisQL API Guide](https://docs.domaintools.com/api/iris/investigate/irisql/). required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/InvestigateRequestParameters' + text/plain: + schema: + type: string + description: | + An IrisQL query for complex domain searches. + Must begin with '# IrisQL-1.0' version comment. + example: | + # IrisQL-1.0 + DOMAIN CONTAINS "example" + AND + RISK_SCORE GREATER_THAN 70 responses: DetectMonitorSuccess: description: OK. A list of monitors was successfully retrieved. @@ -1253,6 +1462,15 @@ components: type: array items: $ref: '#/components/schemas/ApexDomain' + DetectUnprocessableEntity: + description: | + 422: Unprocessable Entity. The request is syntactically valid JSON but + contains values that fail validation. The response includes per-field + error messages. + content: + application/json: + schema: + $ref: '#/components/schemas/DetectValidationError' IrisBadRequest: $ref: '#/components/responses/BadRequest' IrisForbidden: @@ -1360,43 +1578,6 @@ components: - xml description: | The desired response format. - AccountInformation: - type: object - description: Contains the account details and a list of product subscriptions. - properties: - response: - type: object - properties: - account: - $ref: '#/components/schemas/AccountInfoAccount' - products: - type: array - description: A list of product subscriptions including usage limits and expiration dates. - items: - type: object - description: Details for a single product subscription. Keys include id, rate limits, usage, and expiration_date. - example: - id: domain-profile - per_month_limit: '50000' - per_hour_limit: null - per_minute_limit: '120' - absolute_limit: null - usage: - today: '0' - month: '1' - expiration_date: '2027-12-30' - AccountInfoAccount: - type: object - description: Basic details about the API account. - properties: - api_username: - type: string - description: The username associated with the account. - example: bdfidler - active: - type: boolean - description: Indicates if the account is currently active. - example: true ApexDomainList: type: string pattern: ^([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(,([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,})*$ @@ -1404,13 +1585,13 @@ components: CommaSeparatedTags: type: string description: | - A comma-separated list of tag names. Tags are matched exactly and compared case-insensitively unless otherwise specified. + 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. + 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: | @@ -1571,7 +1752,7 @@ components: 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. + 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}(?