openapi: 3.2.0
info:
  title: NordStellar Enterprise Data Credential Lists 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: Credential Lists
  description: 'Endpoints for retrieving detailed metadata about breach origins, including credential lists.

    These operations provide comprehensive context about credential list breach incidents, affected platforms, and exposure scope to support your security investigations.'
paths:
  /email/{email-sha256}/credential-lists:
    get:
      tags:
      - Credential Lists
      summary: Email credential lists lookup
      description: 'Used for looking up email addresses and their credential lists.

        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: singleEmailCredentialLists
      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/EmailCredentialListsSample'
        '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/credential-lists:
    post:
      tags:
      - Credential Lists
      summary: Bulk email credential lists lookup
      description: 'Used for looking up email addresses and their credential lists 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: emailCredentialLists
      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/EmailsCredentialListsSample'
        '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/credential-list/{id}:
    get:
      tags:
      - Credential Lists
      summary: Credential list Lookup
      description: 'Used to look up credential lists that are publicly accessible on the internet, and their metadata.

        These credential lists may have been collected from both clearnet and deep/dark web.

        The origin of these credential lists is not known, they might have been collected from breached databases, by stuffing attacks or other means.


        **Rate limit: 200 per second.**'
      operationId: credentialList
      parameters:
      - $ref: '#/components/parameters/HexId'
      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/CredentialListSample'
        '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/credential-list:
    post:
      tags:
      - Credential Lists
      summary: Bulk credential lists lookup
      description: 'Used to look up credential lists that are publicly accessible on the internet, and their metadata in bulk.

        These credential lists may have been collected from both clearnet and deep/dark web.

        The origin of these credential lists is not known, they might have been collected from breached databases, by stuffing attacks or other means.


        The data is returned using pagination by default, pagination behaviour can be modified using **limit** and **offset** parameters.


        **Rate limit: 200 per second.**'
      operationId: credentialLists
      requestBody:
        content:
          application/json:
            schema:
              required:
              - ids
              type: object
              properties:
                ids:
                  type: array
                  description: 'A list of credential list IDs to lookup.

                    ID should consist of 24 hexadecimal digits.'
                  items:
                    type: string
                  example:
                  - 5f4e1f2e4b1d4d4e4b1d4d4e
                  - 5f4e1f2e4b1d4d4e4b1d4d4f
                limit:
                  type: integer
                  example: 10
                offset:
                  type: integer
                  example: 0
        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/CredentialListsSample'
        '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 lists on single request
          content: {}
      security:
      - ApiKeyAuth: []
components:
  headers:
    X-Quota-Remaining:
      schema:
        type: integer
      description: The number of requests left for the period
    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-Quota-Limit:
      schema:
        type: integer
      description: Quota limit per minute
    X-RateLimit-Reset:
      schema:
        type: string
        format: date-time
      description: Date and time when rate limit counter resets
  schemas:
    CredentialListsSample:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CredentialListSample'
        limit:
          type: integer
          example: 10
        offset:
          type: integer
          example: 0
    EmailCredentialListsSample:
      type: object
      properties:
        id:
          type: string
          example: 2a539d6520266b56c3b0c525b9e6128858baeccb5ee9b694a2906e123c8d6dd3
        email:
          type: string
          example: example@example.com
        credential_lists:
          type: array
          items:
            $ref: '#/components/schemas/CredentialDataItem'
    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
    EmailsCredentialListsSample:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmailCredentialListsSample'
        limit:
          type: integer
          example: 10
        offset:
          type: integer
          example: 0
    CredentialListSample:
      type: object
      properties:
        id:
          type: string
          description: Systemic hex ID of the record
          example: 63bec0fab4f037082c187d70
        type:
          type: string
          description: Credential list type - combo_list or ato_list. ATO list is a list of credentials that have a target domain
          example: combo_list
        date_created:
          type: string
          example: '2023-01-01T00:00:00Z'
        domain:
          type: string
          example: example.com
        valid_credential_count:
          type: integer
          example: 99923
    CredentialDataItem:
      type: object
      properties:
        id:
          type: string
          description: Systemic hex ID of the record
          example: 66c4d3912b183418f7743576
        passwords:
          type: array
          items:
            type: string
          example:
          - password1
          - password2
        published_date:
          type: string
          description: Date when the credential list data was published onto the asset
          example: '2025-01-20T19:04:39Z'
        combos:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                example: example.com
              password:
                type: string
                example: password1
              url:
                type: string
                example: https://example.com/login
        risk_assessment:
          $ref: '#/components/schemas/EmailSample/properties/risk_assessment'
    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.
  parameters:
    Email:
      name: email-sha256
      in: path
      required: true
      description: Hashed lower-cased email address using SHA256 algorithm
      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
  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