openapi: 3.2.0
info:
  title: NordStellar Enterprise Data Cookie Intelligence 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: Cookie Intelligence
  description: 'Endpoints for comprehensive cookie data monitoring in data breaches, including zero-knowledge search capabilities.

    These operations enable robust cookie security protection and exposure assessment.'
paths:
  /zero-knowledge/cookie/{hash-type}/{hash-range}:
    get:
      tags:
      - Cookie Intelligence
      summary: Cookies search
      description: 'Zero knowledge endpoints are endpoints for sensitive data specifically designed to avoid the transfer of such data.


        Used for checking if the specific cookie has been compromised. The

        request must include first 8 characters of the *cookie* value, hashed using

        **SHA-256** algorithm.


        Hashed cookies are returned in a response that start with the filter characters provided in the request.

        **Rate limit: 1000 per second.**'
      operationId: cookiesSearch
      parameters:
      - name: hash-type
        in: path
        required: true
        description: Currently only **sha256**
        schema:
          type: string
      - $ref: '#/components/parameters/HashRange'
      responses:
        '200':
          description: Returns found data
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per second. Defaults 200 per second
            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
            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/ZeroKnowledgeCookiesSample'
        '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: []
  /zero-knowledge/cookie:
    post:
      tags:
      - Cookie Intelligence
      summary: Bulk cookies search
      description: 'Zero knowledge endpoints are endpoints for sensitive data specifically designed to avoid the transfer of such data.


        Used for checking if the specific cookie has been compromised. The

        request must include an array of first 8 characters of the *cookie value*, hashed using

        **SHA-256** algorithm.


        Hashed cookies are returned in a response that start with the filter characters provided in the request.

        One request may have up to *100* hash ranges.


        **Rate limit: 500 per second.**'
      operationId: cookiesBulkSearch
      requestBody:
        content:
          application/json:
            schema:
              required:
              - data
              type: object
              properties:
                hash_ranges:
                  type: array
                  description: A list of hash ranges (8 hexadecimal characters) to lookup zero knowledge data
                  items:
                    type: string
                  example:
                  - '00000000'
                  - ffffffff
        required: true
      responses:
        '200':
          description: Returns found data
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per second. Defaults 200 per second
            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
            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/ZeroKnowledgeCookiesSample'
        '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: []
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
  parameters:
    HashRange:
      name: hash-range
      in: path
      required: true
      schema:
        type: string
  schemas:
    ZeroKnowledgeCookieSample:
      type: object
      properties:
        hash:
          type: string
          description: SHA256 hash of the cookie *value*
          example: 2f8785a49e0e3f5652784701f97474b3ddf7b2a92c8572fc3111eab716349218
        name:
          type: string
          description: Cookie name
          example: auth-token
        path:
          type: string
          description: Cookie path
          example: /
        domain:
          type: string
          description: Cookie domain name
          example: twitch.tv
        expiry_date:
          type: string
          description: Cookie expiration date
          example: '2025-07-21T18:05:22Z'
        data:
          type: array
          description: Contains data grouped by **origin**.
          items:
            type: object
            properties:
              origin:
                type: string
                example: malware_logs
                description: Contains data origin (Currently only **malware_logs**)
              data:
                type: array
                description: Contains origin items with leaked data keys.
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Origin record id.
                      example: 66c4d3912b183418f7743576
                    compromised_data:
                      type: array
                      description: Compromised data keys
                      items:
                        type: string
                      example:
                      - saved_credentials
                      - cookies
                      - autofill_information
    ZeroKnowledgeCookiesSample:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ZeroKnowledgeCookieSample'
  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