openapi: 3.2.0 info: title: NordStellar Enterprise Data Breached Databases API description: '## Overview The NordStellar Enterprise Data API provides comprehensive access to our data breach intelligence platform, enabling organizations to integrate real-time security monitoring and alerting capabilities directly into their existing infrastructure. This API allows you to proactively protect your users by detecting when their sensitive information has been compromised in data breaches across the internet. **Key Features**: - **Real-time Breach Monitoring**: Receive immediate notifications when user data appears in newly discovered data breaches. - **Zero-Knowledge Architecture**: Search for compromised sensitive data (credit cards, national identification numbers) using secure hash-based methods that never transmit the actual sensitive information. - **Comprehensive Data Sources**: Access intelligence from multiple sources including corporate data breaches, malware infection logs, and stolen credential lists. - **Flexible Integration Options**: Support for webhook notifications, bulk operations, and subscription management to fit your organization''s unique requirements. - **Enterprise-Grade Security**: Secure authentication methods, rate limiting, and quota management to ensure responsible and controlled API usage.' version: '3.1' servers: - url: /api/v3/data security: - ApiKeyAuth: [] - BasicAuth: [] tags: - name: Breached Databases description: 'Endpoints for retrieving detailed metadata about breach origins, including databases. These operations provide comprehensive context about database breach incidents, affected platforms, and exposure scope to support your security investigations.' paths: /email/{email-sha256}/databases: get: tags: - Breached Databases summary: Email databases lookup description: 'Used for looking up email addresses and their databases. These email addresses and their data have been collected and aggregated from various databases openly accessible on the internet. **Rate limit: 200 per second.**' operationId: singleEmailDatabases parameters: - $ref: '#/components/parameters/Email' responses: '200': description: Returns found data headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Limit: $ref: '#/components/headers/X-Quota-Limit' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' X-Quota-Reset: $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset' content: application/json: schema: $ref: '#/components/schemas/EmailDatabasesSample' '400': description: Bad request content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '401': description: Unauthorized content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '404': description: No data found content: {} security: - ApiKeyAuth: [] /email/databases: post: tags: - Breached Databases summary: Bulk email databases lookup description: 'Used for looking up email addresses and their databases in bulk. These email addresses and their data have been collected and aggregated from various databases openly accessible on the internet. The data is returned using pagination by default, pagination behaviour can be modified using **limit** and **offset** parameters. **Rate limit: 200 per second.**' operationId: emailDatabases requestBody: content: application/json: schema: $ref: '#/components/schemas/Emails' required: true responses: '200': description: Returns found data headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Limit: $ref: '#/components/headers/X-Quota-Limit' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' X-Quota-Reset: $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset' content: application/json: schema: $ref: '#/components/schemas/EmailsDatabasesSample' '400': description: Bad request content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '401': description: Unauthorized content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' security: - ApiKeyAuth: [] /phone/{phone-sha256}/databases: get: tags: - Breached Databases summary: Phone databases lookup description: 'Used for looking up phone numbers and their databases. These phone numbers and their data have been collected and aggregated from various databases openly accessible on the internet. **Rate limit: 200 per second.**' operationId: singlePhoneDatabases parameters: - $ref: '#/components/parameters/Phone' responses: '200': description: Returns found data headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Limit: $ref: '#/components/headers/X-Quota-Limit' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' X-Quota-Reset: $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset' content: application/json: schema: $ref: '#/components/schemas/PhoneDatabasesSample' '400': description: Bad request content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '401': description: Unauthorized content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '404': description: No data found content: {} security: - ApiKeyAuth: [] /phone/databases: post: tags: - Breached Databases summary: Bulk phone databases lookup description: 'Used for looking up phones numbers and their databases in bulk. These phone numbers and their data have been collected and aggregated from various databases openly accessible on the internet. The data is returned using pagination by default, pagination behaviour can be modified using **limit** and **offset** parameters. **Rate limit: 200 per second.**' operationId: phonesDatabases requestBody: content: application/json: schema: $ref: '#/components/schemas/Phone' required: true responses: '200': description: Returns found data headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Limit: $ref: '#/components/headers/X-Quota-Limit' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' X-Quota-Reset: $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset' content: application/json: schema: $ref: '#/components/schemas/PhonesDatabasesSample' '400': description: Bad request content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '401': description: Unauthorized content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' security: - ApiKeyAuth: [] /data-source/database/{id}: get: tags: - Breached Databases summary: Database Lookup description: 'Used to look up breached databases, that are publicly accessible on the internet, and their metadata. These databases may have been collected from both clearnet and deep/dark web. The breach date of these databases is by no means exact, since, if no official statement by the breached company is made, it is taken from the data publication source, be it a hacker forum, a ransomware group website or some place else. Database description can not exceed 1000 characters. **Rate limit: 200 per second.**' operationId: database parameters: - $ref: '#/components/parameters/HexId' - $ref: '#/paths/~1data-source~1database/post/parameters/0' - $ref: '#/paths/~1data-source~1database/post/parameters/1' responses: '200': description: Returns found data headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Limit: $ref: '#/components/headers/X-Quota-Limit' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' X-Quota-Reset: $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset' content: application/json: schema: $ref: '#/components/schemas/DatabaseSample' '400': description: Bad request content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '401': description: Unauthorized content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '404': description: No data found content: {} security: - ApiKeyAuth: [] /data-source/database/domain/{domain}: get: tags: - Breached Databases summary: Database Lookup by Domain description: "Used to look up breached databases, that are publicly accessible on the internet, and their metadata.\nThese databases may have been collected from both clearnet and deep/dark web.\nThe breach date of these databases is by no means exact, since, if no official statement by the breached company is made, it is taken from the data publication source, be it a hacker forum, a ransomware group website or some place else.\nDatabase description can not exceed 1000 characters. \n\n**Rate limit: 200 per second.**" operationId: databaseByDomain parameters: - $ref: '#/components/parameters/Domain' - $ref: '#/paths/~1data-source~1database/post/parameters/0' - $ref: '#/paths/~1data-source~1database/post/parameters/1' responses: '200': description: Returns found data headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Limit: $ref: '#/components/headers/X-Quota-Limit' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' X-Quota-Reset: $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset' content: application/json: schema: $ref: '#/components/schemas/DatabaseSample' '400': description: Bad request content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '401': description: Unauthorized content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '404': description: No data found content: {} security: - ApiKeyAuth: [] /data-source/database: post: tags: - Breached Databases summary: Bulk databases lookup description: 'Used to look up breached databases, that are publicly accessible on the internet, and their metadata in bulk. These databases may have been collected from both clearnet and deep/dark web. The breach date of these databases is by no means exact, since, if no official statement by the breached company is made, it is taken from the data publication source, be it a hacker forum, a ransomware group website or some place else. Database description can not exceed 1000 characters. **One of the following fields in request body is required: ids, date_from** The databases can be lookuped **either** by **id** or by **published_date**. If **ids** are provided, the lookup is executed using them. If you wish to lookup databases by **published_date**, fill in **published_date_from**, **published_date_to** and leave **ids** empty or absent. **Providing both ids and published_date_from or published_date_to will result in 400 BAD REQUEST response.** The data is returned using pagination by default, pagination behaviour can be modified using **limit** and **offset** parameters. **Rate limit: 200 per second.**' operationId: databases parameters: - name: inclusive-projection in: query description: 'Return **only** the listed fields of the database record, omitting everything else. Values are a comma-separated list (`?inclusive-projection=name,breach_date`) or repeated parameters (`?inclusive-projection=name&inclusive-projection=breach_date`). **Available fields:** `id`, `name`, `identifier`, `type`, `domain`, `breach_date`, `description`, `logo_url`, `data_keys`, `unique_email_count`, `unique_phone_count`, `published` (controls the `published_date` response field). Only the listed fields are returned — there are no implicit includes beyond the always-present `id`. **`id` is special:** it is always present and may be named explicitly, but it can never be excluded. Mutually exclusive with **exclusive-projection** — supplying both returns `400 Bad Request`. Unknown field names also return `400 Bad Request`. A maximum of 100 fields may be supplied.' required: false style: form explode: false schema: type: array items: type: string example: - name - breach_date - name: exclusive-projection in: query description: 'Return the full database record **except** the listed fields. Values are a comma-separated list (`?exclusive-projection=data_keys,description`) or repeated parameters (`?exclusive-projection=data_keys&exclusive-projection=description`). **Available fields:** `name`, `identifier`, `type`, `domain`, `breach_date`, `description`, `logo_url`, `data_keys`, `unique_email_count`, `unique_phone_count`, `published` (controls the `published_date` response field). **`id` cannot be excluded** — supplying `id` returns `400 Bad Request`. Mutually exclusive with **inclusive-projection** — supplying both returns `400 Bad Request`. Unknown field names also return `400 Bad Request`. A maximum of 100 fields may be supplied.' required: false style: form explode: false schema: type: array items: type: string example: - data_keys requestBody: content: application/json: schema: $ref: '#/components/schemas/Databases' required: true responses: '200': description: Returns found data headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Limit: $ref: '#/components/headers/X-Quota-Limit' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' X-Quota-Reset: $ref: '#/paths/~1email/post/responses/200/headers/X-Quota-Reset' content: application/json: schema: $ref: '#/components/schemas/DatabasesSample' '400': description: Bad request content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '401': description: Unauthorized content: application/json: schema: $ref: '#/paths/~1user/get/responses/400/content/application~1json/schema' '413': description: Too many emails on single request content: {} security: - ApiKeyAuth: [] components: headers: X-Quota-Remaining: schema: type: integer description: The number of requests left for the period X-Quota-Limit: schema: type: integer description: Quota limit per minute X-RateLimit-Limit: schema: type: integer description: Request limit per minute X-RateLimit-Remaining: schema: type: integer description: The number of requests left for the time window X-RateLimit-Reset: schema: type: string format: date-time description: Date and time when rate limit counter resets schemas: EmailDatabasesSample: type: object properties: id: type: string example: 2a539d6520266b56c3b0c525b9e6128858baeccb5ee9b694a2906e123c8d6dd3 email: type: string example: example@example.com databases: type: array items: $ref: '#/components/schemas/DatabaseDataItem' DatabaseDataItem: type: object properties: identifier: type: string description: Identifier in the following format {domain}_{top level domain} example: example_com id: type: string description: Systemic hex ID of the record example: 66c4d3912b183418f7743576 published_date: type: string description: Date when the database data was published onto the asset example: '2025-01-20T19:04:39Z' data: type: array items: type: object properties: key: type: string description: Key of the data point, complete list can be found [HERE](https://docs.nordstellar.com/enterprise-apis/product-integrations/data-categories#data-points) example: password value: type: array items: type: string description: Value of the data point example: - password1 - password2 risk_assessment: $ref: '#/components/schemas/EmailSample/properties/risk_assessment' EmailsDatabasesSample: type: object properties: data: type: array items: $ref: '#/components/schemas/EmailDatabasesSample' limit: type: integer example: 10 offset: type: integer example: 0 PhonesDatabasesSample: type: object properties: data: type: array items: $ref: '#/components/schemas/PhoneDatabasesSample' limit: type: integer example: 10 offset: type: integer example: 0 DatabasesSample: type: object properties: data: type: array items: $ref: '#/components/schemas/DatabaseSample' limit: type: integer example: 10 offset: type: integer example: 0 Phone: required: - data type: object properties: phones_sha256: type: array description: A list of SHA256 hashed phone numbers to lookup items: type: string example: - 2fc8583f3be53fcf1a6e0f972869478e392ef2a6f62b7b3735ca53af921ea304 limit: description: Default is the maximum limit of 100 records type: integer example: 10 offset: type: integer example: 0 PhoneDatabasesSample: type: object properties: id: type: string example: 631dadc9288c13b61bb83c480292c11154b35b5bb777a4946980de62f70477eb phone: type: string example: '13855550193' description: International format phone number databases: type: array items: $ref: '#/components/schemas/DatabaseDataItem' EmailSample: type: object properties: id: type: string example: 2a539d6520266b56c3b0c525b9e6128858baeccb5ee9b694a2906e123c8d6dd3 email: type: string example: example@example.com databases: type: array items: $ref: '#/components/schemas/DatabaseDataItem' malware_logs: type: array items: $ref: '#/components/schemas/MalwareDataItem' credential_lists: type: array items: $ref: '#/components/schemas/CredentialDataItem' risk_assessment: type: object properties: level: type: string description: 'Risk level, one of the following: info, low, medium, high, critical' example: high recommendations_enabled: type: string description: If true, user has enabled recommendations for this request. If false, recommendations are not provided. This field is taken from user provided query parameter of the same name. example: 'true' recommendations: type: array items: type: object properties: leaked_data_category: type: string description: Pretty name of general data category that triggered this recommendation example: Password recommendation: type: string description: Recommendation text example: Avoid using your publicly known information in passwords. Threat actors routinely use other known information, such as email addresses, phone numbers, pet names, dates of birth, first/last names and other data in stuffing attacks to uncover passwords that were otherwise never leaked online. DatabaseSample: type: object properties: identifier: type: string description: Identifier in the following format {domain}_{top level domain} example: example_com id: type: string description: Systemic hex ID of the record example: 6698de5af71724f56f4076df breach_date: type: string example: '2024-01-16T00:00:00Z' data_keys: type: array items: type: string description: List of data keys that are exposed in the database, all possible values can be found [HERE](https://docs.nordstellar.com/enterprise-apis/product-integrations/data-categories#data-points) example: - alternate_email - bio - email - homepage - name - profile_picture - username description: type: string example: On July 18, 2024, a database related to the example.com website was found circulating the web. The potential data leak reportedly occurred on January 16, 2024. Over 15 million email addresses were exposed, together with social media, credential and personal data. Leaked records include username, name, home page, bio, Parent email address and Profile picture's URL. The validity of the data exposed couldn't be verified. Yet we're still informing you about a potential data leak – but keep in mind there's a chance of it being a false positive. logo_url: type: string example: null name: type: string example: example.com published_date: type: string example: '2024-07-18T09:20:26Z' unique_email_count: type: integer example: 15111576 unique_phone_count: type: integer example: 123516 type: type: string description: Type of the database - identified (has a domain or name), unidentified or collection example: identified domain: type: string example: example.com Emails: required: - data type: object properties: emails_sha256: type: array description: A list of SHA256 hashed lower-case email addresses to lookup items: type: string example: - 2fc8583f3be53fcf1a6e0f972869478e392ef2a6f62b7b3735ca53af921ea304 limit: description: Default is the maximum limit of 100 records type: integer example: 10 offset: type: integer example: 0 Databases: type: object properties: ids: type: array description: 'A list of database IDs to lookup. ID should consist of 24 hexadecimal digits.' items: type: string example: - 5f4e1f2e4b1d4d4e4b1d4d4e - 5f4e1f2e4b1d4d4e4b1d4d4f published_date_from: type: string description: A date from filter. Has to be in ISO 8601 format YYYY-MM-DD example: '2021-01-01' published_date_to: type: string description: A date to filter. Has to be in ISO 8601 format YYYY-MM-DD. Default is todays date example: '2021-01-02' limit: description: Default is the maximum limit of 1000 records type: integer example: 10 offset: type: integer example: 0 parameters: Email: name: email-sha256 in: path required: true description: Hashed lower-cased email address using SHA256 algorithm schema: type: string Domain: name: domain in: path required: true schema: type: string HexId: name: id in: path required: true description: Record ID to lookup. ID should consist of 24 hexadecimal digits. schema: type: string Phone: name: phone-sha256 in: path required: true description: Hashed phone number using SHA256 algorithm schema: type: string securitySchemes: BasicAuth: type: http scheme: basic description: Authorization string. Needs to be in the standard BasicAuth format - "Basic BASE64_CREDENTIALS", where BASE64_CREDENTIALS is the user username:password encoded in base64 format. ApiKeyAuth: type: apiKey in: header name: X-API-KEY