openapi: 3.0.3
info:
  title: Pulsedive API Reference
  version: 1.0.0
  description: >
    The Pulsedive API lets you programmatically manage resources within
    Pulsedive.

    Users can look up known indicators and threats, enrich and investigate
    indicators, query Pulsedive data, and automate workflows.


    Please report any discrepancies in API behavior to <a
    href="mailto:support@pulsedive.com">Pulsedive Support</a>.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    email: support@pulsedive.com
externalDocs:
  url: https://docs.pulsedive.com
servers:
  - url: https://pulsedive.com
tags:
  - name: Scan
    description: >
      Queue an indicator for scanning and poll to retrieve enriched threat
      intelligence results.


      ## Workflow


      1. Submit an indicator.
          Add an indicator to the scanning queue and receive a queue ID.
      2. Poll for results.
          Use the queue ID to check progress and retrieve data.

      ## Storage Behavior


      Scan indicators without permanently storing them in Pulsedive. This
      performs the same enrichment and risk scoring as submitting through the
      UI, but the data isn't stored. If the indicator already exists in the
      database, however, its information will be updated.


      <Note>

      For bulk scans, use the UI's [Analyze](https://pulsedive.com/analyze/)
      page.

      </Note>
  - name: Explore
    description: Search for indicators using query language.
paths:
  /api/analyze.php:
    post:
      x-displayOrder: 1
      tags:
        - Scan
      x-codeSamples:
        - lang: curl
          label: Add to Queue
          source: |
            curl "https://pulsedive.com/api/analyze.php?value=pulsedive.com"
        - lang: curl
          label: Safe Indicator Handling
          source: >
            curl
            "https://pulsedive.com/api/analyze.php?ioc=cHVsc2VkaXZlLmNvbQ%3D%3D&probe=1"
      summary: Add Indicator to the Queue
      x-mint:
        href: /api/scan/add
      description: >
        Add an indicator to the scanning queue and receive a queue ID, so you
        can poll for results.
      operationId: scanIndicatorByValue
      parameters:
        - $ref: '#/components/parameters/APIKey'
        - $ref: '#/components/parameters/Indicator'
        - $ref: '#/components/parameters/IOC'
        - $ref: '#/components/parameters/Probe'
        - $ref: '#/components/parameters/Submit'
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Successful request. Returns scan queue information in JSON format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      x-displayOrder: 2
      tags:
        - Scan
      x-codeSamples:
        - lang: curl
          label: Poll for Results
          source: |
            curl "https://pulsedive.com/api/analyze.php?qid=2350183660"
      summary: Poll for Scan Results
      x-mint:
        href: /api/scan/poll
      description: >
        Poll for scan results using the queue ID returned from the POST request.


        Returns processing status while the scan is in progress, then complete
        results when finished.


        Polling requests don't count against your rate limit, but please poll
        responsibly. (We recommend at most every 500ms.)
      operationId: scanRetrieveResult
      parameters:
        - $ref: '#/components/parameters/APIKey'
        - $ref: '#/components/parameters/QID'
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Successful request. Returns scan status or complete results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/explore.php:
    get:
      tags:
        - Explore
      x-codeSamples:
        - lang: curl
          label: Search Dataset
          source: >
            curl
            "https://pulsedive.com/api/explore.php?q=ioc%3Dpulsedive.com%20or%20threat%3Dryuk"
        - lang: curl
          label: Export to CSV
          source: >
            curl
            "https://pulsedive.com/api/explore.php?q=ioc%3Dpulsedive.com%20or%20threat%3Dryuk&format=csv"
        - lang: curl
          label: Export to STIX 2.1
          source: >
            curl
            "https://pulsedive.com/api/explore.php?q=ioc%3Dpulsedive.com%20or%20threat%3Dryuk&format=stix"
      summary: Search Dataset
      x-mint:
        href: /api/explore/search
      description: >
        Query Pulsedive's dataset using the Explore query language. Search
        across indicators or threats by value, type, risk, timestamps, feeds,
        attributes, and properties using boolean logic and wildcards.


        The Explore query language provides powerful search capabilities:


        - **Boolean operators**: Combine search terms with `and`, `or`, `not`

        - **Wildcards**: Use `*` for pattern matching

        - **Field-specific queries**: Search by specific fields like `ioc=`,
        `type=`, `risk=`, `threat=`, `feed=`

        - **Complex filters**: Filter by timestamps, attributes, and technical
        properties


        For detailed query syntax and more examples, visit [Query
        Language](/api/explore/query-language/).
      operationId: searchIndicators
      parameters:
        - $ref: '#/components/parameters/APIKey'
        - $ref: '#/components/parameters/Q'
        - $ref: '#/components/parameters/Type'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/OutputFormat'
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Successful request. Returns search results in the specified format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExploreIndicatorsResponse'
            text/csv:
              schema:
                $ref: '#/components/schemas/CSVResponse'
              example: >
                # 

                # PULSEDIVE - 2025-11-17 02:26:24 UTC

                # 

                # QUERY

                # ioc=pulsedive.com or threat=ryuk

                # 

                # RESULT LIMIT: 10

                # 

                #
                https://pulsedive.com/explore/?q=ioc%3Dpulsedive.com%20or%20threat%3Dryuk

                # 

                indicator,type,risk,stamp_added,stamp_updated,stamp_seen,stamp_retired,reference,geo_city,geo_country,geo_countrycode,geo_org,dns_ptr

                pulsedive.com,domain,none,"2017-10-04 01:20:55","2025-11-16
                17:00:13","2025-11-16
                17:00:13",,https://pulsedive.com/indicator/?iid=53929,"REDACTED
                FOR PRIVACY","United States of America",US,,

                target-support.online,domain,medium,"2020-02-11
                16:33:26","2025-10-05 08:10:08","2025-10-05
                08:10:08",,https://pulsedive.com/indicator/?iid=8342625,"San
                Mateo","United States of America",US,,

                web-analysis.live,domain,medium,"2020-02-12
                00:06:29","2025-06-16 05:29:30","2025-03-13
                22:58:24","2025-06-16
                05:29:30",https://pulsedive.com/indicator/?iid=8430082,"LOS
                ANGELES","United States of America",US,,

                renovatesystem.com,domain,low,"2020-02-20 13:37:14","2022-06-28
                04:32:48","2022-03-25 08:37:51","2022-06-28
                04:32:48",https://pulsedive.com/indicator/?iid=8963066,Drums,"United
                States of America",US,,

                serviceboostnumberone.com,domain,low,"2020-03-24
                01:45:24","2022-03-23 07:10:22","2022-03-23
                07:10:22","2022-01-18
                01:06:26",https://pulsedive.com/indicator/?iid=10517362,Drums,"United
                States of America",US,,

                service-updater.com,domain,medium,"2020-04-03
                04:17:21","2022-06-28 04:32:48","2022-03-25
                17:03:02","2022-06-28
                04:32:48",https://pulsedive.com/indicator/?iid=10903232,,"Virgin
                Islands (British)",VG,,

                microsoftupdateswin.com,domain,high,"2020-04-03
                04:17:27","2024-03-19 10:36:07","2024-03-19
                10:36:07","2022-06-16
                02:23:46",https://pulsedive.com/indicator/?iid=10903235,[privacy],[privacy],,[privacy],

                updatemanagir.us,domain,low,"2020-04-03 06:55:41","2022-03-26
                00:58:52","2022-03-26 00:58:52","2022-02-03
                17:25:52",https://pulsedive.com/indicator/?iid=10910031,,,,,

                topserviceupdater.com,domain,medium,"2020-04-03
                06:55:46","2022-06-19 02:59:21","2022-03-16
                06:11:24","2022-06-19
                02:59:21",https://pulsedive.com/indicator/?iid=10910034,[privacy],[privacy],,[privacy],

                topservicesecurity.net,domain,medium,"2020-04-03
                06:55:53","2024-06-20 13:13:26","2024-03-19
                11:00:36","2024-06-20
                13:13:26",https://pulsedive.com/indicator/?iid=10910041,[privacy],[privacy],,[privacy],
            application/stix+json:
              schema:
                $ref: '#/components/schemas/STIXResponse'
              example:
                objects:
                  - id: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    type: identity
                    name: Pulsedive
                    identity_class: organization
                    sectors:
                      - technology
                    contact_information: https://pulsedive.com/
                    description: >-
                      Pulsedive is an analyst-centric threat intelligence
                      platform built with on-demand scanning for live data, risk
                      scoring to reduce false positives, and powerful
                      integration capabilities for leveraging Pulsedive data
                      inside your organization.
                    created: '2026-02-08T08:56:18.000Z'
                    modified: '2026-02-08T08:56:18.000Z'
                    spec_version: '2.1'
                    lang: en
                  - id: extension-definition--c58a936d-f97f-545b-9646-434cc3382126
                    type: extension-definition
                    name: Pulsedive Indicator Extension
                    description: >-
                      This schema adds Pulsedive-specific properties to
                      Indicator objects.
                    schema: https://pulsedive.com/api/taxii
                    version: 1.0.0
                    extension_types:
                      - toplevel-property-extension
                    extension_properties:
                      - pulsedive_risk
                      - pulsedive_risk_int
                      - pulsedive_retired
                      - pulsedive_retired_timestamp
                      - pulsedive_retired_reason
                    created: '2026-02-08T08:56:18.000Z'
                    modified: '2026-02-08T08:56:18.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                  - id: indicator--606a6a6a-bec0-5fb3-9203-000077081047
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T08:39:49.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''register-polymarket.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T08:39:49.000Z'
                    modified: '2026-02-07T08:40:14.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--e8989e12-a49a-5614-a49c-000077081056
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T08:39:53.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''kraken-world.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T08:39:53.000Z'
                    modified: '2026-02-07T08:40:52.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--54783807-ff40-57e9-9f33-000077081057
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T08:39:54.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''zentral-invest.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T08:39:54.000Z'
                    modified: '2026-02-07T08:41:11.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--c2939ac3-4eef-5e08-90e7-000077082902
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T08:43:05.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''point-fort-fichet-courbevoie.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T08:43:05.000Z'
                    modified: '2026-02-07T08:43:26.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--23236d25-ed94-5bd4-a1e0-000077083237
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T09:34:25.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''783yto.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T09:34:25.000Z'
                    modified: '2026-02-07T09:34:34.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--a7aa2b33-7743-5d00-9560-000077083252
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T09:34:25.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''746ytt.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T09:34:25.000Z'
                    modified: '2026-02-07T09:34:34.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--fe622958-12ca-5c54-8899-000077083253
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T09:34:25.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''5742kyx.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T09:34:25.000Z'
                    modified: '2026-02-07T09:34:34.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--502373cb-ce74-54c4-bb5c-000077083241
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T09:34:25.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''9874yt.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T09:34:25.000Z'
                    modified: '2026-02-07T09:34:35.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--5c91c153-dd55-5ce0-8e64-000077083246
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T09:34:25.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''tba8513.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T09:34:25.000Z'
                    modified: '2026-02-07T09:34:35.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
                  - id: indicator--9b9e796a-0e68-5afe-9773-000077083236
                    type: indicator
                    pulsedive_risk: critical
                    pulsedive_risk_int: 4
                    pulsedive_retired: 0
                    name: Detection Pattern
                    description: Very high risk of malicious activity.
                    valid_from: '2026-02-07T09:34:24.000Z'
                    indicator_types:
                      - malicious-activity
                    pattern: '[domain-name:value = ''greenmort.com'']'
                    pattern_type: stix
                    extensions:
                      extension-definition--c58a936d-f97f-545b-9646-434cc3382126:
                        extension_type: toplevel-property-extension
                    created: '2026-02-07T09:34:24.000Z'
                    modified: '2026-02-07T09:34:36.000Z'
                    created_by_ref: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
                    spec_version: '2.1'
                    lang: en
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    APIKey:
      name: key
      in: query
      required: false
      description: >
        Your Pulsedive API key.


        API key authentication is optional. However, requests without a key have
        stricter rate limits. We recommend including an API key for better
        performance and reliability.
      schema:
        type: string
    Pretty:
      name: pretty
      in: query
      required: false
      description: |
        Indicates whether to format returned JSON results.

        For pretty-printed output, set to `1`.
        For compact output, set to `0`.
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      examples:
        compact:
          summary: Compact output
          value: 0
        pretty:
          summary: Pretty-printed output
          value: 1
    Indicator:
      name: value
      in: query
      required: false
      description: |
        Value of the indicator to scan. May be:

        - a domain name (e.g., `microsoft.com`)
        - an IP address (e.g., `8.8.8.8`)
        - a URL (e.g., `https://pulsedive.com/explore`)

        To use a base64-encoded indicator, use the `ioc` parameter instead.
      schema:
        type: string
      examples:
        ip:
          summary: IPv4 address
          value: 8.8.8.8
        domain:
          summary: Domain name
          value: microsoft.com
        url:
          summary: URL
          value: https://pulsedive.com/explore
    IOC:
      name: ioc
      in: query
      required: false
      description: >
        Base64-encoded value of the indicator to scan.


        Useful for safely transmitting indicators that contain special
        characters or when the indicator is not being processed correctly
        through the `indicator` parameter. (If this is happening, please let us
        know.)


        Use this parameter instead of `indicator` when submitting base64-encoded
        data.
      schema:
        type: string
      examples:
        base64domain:
          summary: Base64-encoded domain
          value: cHVsc2VkaXZlLmNvbQ==
        base64url:
          summary: Base64-encoded URL
          value: aHR0cHM6Ly9wdWxzZWRpdmUuY29tL2V4cGxvcmU=
    Probe:
      name: probe
      in: query
      required: false
      description: >
        Scan type for the indicator.


        Passive scans collect data without direct contact, such as through WHOIS
        and DNS requests. Active scans include port scanning and web browser
        analysis, which are more detectable.


        For active scanning, set to `1`.

        For passive scanning, set to `0`.
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      examples:
        passive:
          summary: Passive scan
          value: 0
        active:
          summary: Active scan
          value: 1
    Submit:
      name: submit
      in: query
      required: false
      description: >
        Controls whether to save the scanned indicator to Pulsedive's database.


        To store the indicator and make it searchable in future queries, set to
        `1`.

        To scan and enrich without storing, set to `0`.


        If you scan an indicator that already exists in the database, Pulsedive
        updates it with fresh scan results regardless of this parameter's value.
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      examples:
        submit:
          summary: Store indicator
          value: 1
        no_submit:
          summary: Don't store indicator
          value: 0
    QID:
      name: qid
      in: query
      required: true
      description: >
        Unique identifier of the request to retrieve. (Queue ID returned when
        you added the indicator to the queue for scanning.)
      schema:
        type: integer
        example: 2100188839
    Q:
      name: q
      in: query
      required: true
      description: >
        Explore query string using the Explore query language syntax. The query
        is URI-encoded.


        Query syntax supports:


        - **Field searches**: `ioc=example.com`, `type=domain`, `risk=high`

        - **Boolean logic**: `ioc=pulsedive.com or threat=ryuk`

        - **Wildcards**: `ioc=*.pulsedive.com`, `feed=*malware*`

        - **Negation**: `not risk=none`

        - **Combinations**: `(type=domain or type=ip) and risk=critical`


        Common searchable fields include `ioc`, `type`, `risk`, `threat`,
        `feed`, `seen`, `added`, `updated`, `retired`, `port`, `protocol`, and
        `technology`.


        Some examples:

        - [Paypal brand
        abuse](https://pulsedive.com/explore/?q=type=domain%20ioc!=*paypal.com%20ioc=*paypal.com*)

        - [Web servers using
        PHP](https://pulsedive.com/explore/?q=port=80%20and%20port=443%20and%20technology=php)

        -
        [DigitalOcean](https://pulsedive.com/explore/?q=whois.++registrant=DigitalOcean*)


        For detailed query syntax and more examples, visit [Query
        Language](/api/explore/query-language/).
      schema:
        type: string
      examples:
        basic:
          summary: Basic indicator search
          value: ioc=pulsedive.com
        threat:
          summary: Search by threat
          value: threat=ryuk
        boolean:
          summary: Boolean query
          value: ioc=pulsedive.com or threat=ryuk
        risk_filter:
          summary: Risk level filter
          value: risk=critical and type=domain
        wildcard:
          summary: Wildcard search
          value: ioc=*.example.com
    Type:
      name: type
      in: query
      required: false
      description: >
        Search mode, which determines the dataset you are querying and filters
        that are available. Options include:
          
        -  `indicators`: Search for indicators by value, type, risk, attributes,
        properties, and associated threats or feeds.

        - `threats`: Search for threats by name, alias, category, or associated
        indicator attributes.
      schema:
        type: string
        enum:
          - indicators
          - threats
        default: indicators
    Limit:
      name: limit
      in: query
      required: false
      description: >
        Maximum number of results to return per query.


        If you don't specify a limit, Pulsedive applies your account tier's
        default:


        - Visitor (not logged in): `10`

        - Free: `50`

        - Pro: `250`

        - Team: `1000`

        - Business/Custom: `10000`
      schema:
        type: integer
        minimum: 1
        example: 10
    OutputFormat:
      name: format
      in: query
      required: false
      description: >
        Output format for results.


        Available formats:


        - `json`: JSON format (default)

        - `csv`: Comma-separated values with headers

        - `stix`: STIX 2.1 format (requires authentication)


        CSV exports include a header with query information and result limit.
        STIX exports require a registered user account.
      schema:
        type: string
        enum:
          - json
          - csv
          - stix
        default: json
      examples:
        json:
          summary: JSON output
          value: json
        csv:
          summary: CSV export
          value: csv
        stix:
          summary: STIX 2.1 export
          value: stix
  schemas:
    ScanResponse:
      type: object
      properties:
        qid:
          type: integer
          description: |
            Unique identifier of the scan request (Queue ID).
          example: '2100254203'
      additionalProperties:
        type: string
        description: >
          Dynamic key-value pair representing the outcome of your request.


          Each `{key}` represents the overall outcome of your request. The
          `{value}` string provides additional context for the outcome. Until
          your request is complete, the `{key}` will be `error`.
        example:
          error: Added request to queue.
    ProcessingResponse:
      oneOf:
        - $ref: '#/components/schemas/ProcessingState'
        - $ref: '#/components/schemas/CompletedState'
    ProcessingState:
      type: object
      title: Processing
      description: Response while scan is in progress.
      properties:
        qid:
          $ref: '#/components/schemas/QidResponseProperty'
        status:
          type: string
          description: Overall processing state of the request.
          example: processing
        stage:
          type: string
          description: >-
            Current step of the scanning process. Present when scanning is in
            progress.
          example: sending request
      additionalProperties:
        type: string
        description: >
          Dynamic key-value pair representing the outcome of your request.


          Each `{key}` represents the overall outcome of your request. The
          `{value}` string provides additional context for the outcome. Until
          your request is complete, `the {key}` will be `error`.
        example:
          error: Request(s) still processing.
      example:
        qid: 2100254203
        status: processing
        stage: sending request
        error: Request(s) still processing.
    CompletedState:
      type: object
      title: Completed
      description: Response when scan is complete.
      properties:
        qid:
          $ref: '#/components/schemas/QidResponseProperty'
        status:
          type: string
          description: Overall processing state of the request.
          example: done
        data:
          description: >
            Processed results associated with the submitted request. Present
            only when scanning is complete.
          $ref: '#/components/schemas/IndicatorResponse'
      additionalProperties:
        type: string
        description: >
          Dynamic key-value pair representing the outcome of your request.


          Each `{key}` represents the overall outcome of your request. The
          `{value}` string provides additional context for the outcome. Once
          your request is complete, the `{key}` will be `success`.
        example:
          success: Submitted indicator.
      example:
        qid: 2100254203
        status: done
        success: Scan completed successfully.
        data:
          iid: 12345
          indicator: example.com
          type: domain
          risk: medium
    QidResponseProperty:
      type: integer
      description: Unique identifier of the associated request.
      example: '2100254203'
    IndicatorResponse:
      type: object
      properties:
        qid:
          type: integer
          description: >
            Unique identifier of an associated previous submission request, if
            available.
        iid:
          type: integer
          description: Unique identifier of the indicator.
        indicator:
          type: string
          description: Value of the indicator being assessed.
        type:
          type: string
          description: Type of indicator.
          enum:
            - domain
            - ip
            - url
        risk:
          type: string
          description: >
            Final risk score for the indicator.


            If a user has manually adjusted the risk score, this value may
            differ from the recommended risk score.

            In this case, `manualrisk` is set to `1`.
          enum:
            - retired
            - none
            - unknown
            - very low
            - low
            - medium
            - high
            - critical
        risk_recommended:
          type: string
          description: Recommended risk level based on Pulsedive automated risk scoring.
          enum:
            - retired
            - none
            - unknown
            - very low
            - low
            - medium
            - high
            - critical
        manualrisk:
          type: integer
          description: >
            Indicates whether the risk score has been manually adjusted.


            When set to `1`, the risk score has been manually adjusted.

            When set to `0`, the risk score reflects Pulsedive's automated
            assessment.
          enum:
            - 0
            - 1
        retired:
          type: integer
          description: >
            Indicates whether this indicator is inactive or obsolete.


            An indicator is automatically retired if, in the past three months,
            it has not been:


            - Reported using the Seen button in the Pulsedive UI

            - Observed in any source feeds

            - Submitted through the Analyze section of the Pulsedive UI


            Pulsedive research can also retire indicators manually.


            When set to `1`, this indicator is retired.

            When set to `0`, this indicator is active.
          enum:
            - 0
            - 1
          nullable: true
        stamp_added:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was first added to Pulsedive. 24-hour
            format, UTC time zone.
          nullable: true
          example: '2025-05-19 14:23:45'
        stamp_updated:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator record was last updated in Pulsedive.
            24-hour format, UTC time zone.
          nullable: true
          example: '2025-05-19 14:23:45'
        stamp_seen:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was last reported or seen in feeds or
            user submissions in Pulsedive. 24-hour format, UTC time zone.
          nullable: true
          example: '2025-05-19 14:23:45'
        stamp_probed:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was last actively scanned (probed) by
            Pulsedive. 24-hour format, UTC time zone.
          nullable: true
          example: '2025-05-19 14:23:45'
        stamp_retired:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was retired in Pulsedive, if
            applicable. 24-hour format, UTC time zone.
          nullable: true
          example: '2025-05-19 14:23:45'
        recent:
          type: integer
          description: >
            Indicates whether this indicator has had recent activity. Deprecated
            and non-functional.


            When set to `1`, the indicator has had recent activity.

            When set to `0`, the indicator has not had recent activity.
          enum:
            - 0
            - 1
        submissions:
          type: integer
          description: Number of times the indicator has been submitted by any user.
        umbrella_rank:
          type: integer
          description: >
            Rank of the indicator on Cisco Umbrella's top one million domains
            list.

            This list reflects the most frequently queried domains, based on
            passive DNS data across Cisco's global Umbrella network.
          example: 11032
        umbrella_domain:
          type: string
          description: >
            Canonical (base) domain as recognized by Cisco Umbrella. Populated
            when `umbrella_rank` is present.
        riskfactors:
          type: array
          description: List of risk factors influencing this indicator's score.
          items:
            type: object
            properties:
              rfid:
                type: integer
                description: Unique identifier of the risk factor.
              description:
                type: string
                description: Explanation of the risk factor.
                example: found in threat feeds
              risk:
                type: string
                description: Risk level associated with the risk factor.
                enum:
                  - retired
                  - none
                  - unknown
                  - very low
                  - low
                  - medium
                  - high
                  - critical
        redirects:
          type: object
          description: Redirect relationships involving this indicator.
          properties:
            from:
              type: array
              description: Other indicators that redirect to this indicator.
              items:
                type: object
                properties:
                  iid:
                    type: integer
                    description: Unique identifier of other indicator.
                  indicator:
                    type: string
                    description: |
                      Value for other indicator.

                      May be:

                      - a domain name (e.g., `microsoft.com`)
                      - an IP address (e.g., `8.8.8.8`)
                      - a URL (e.g., `https://pulsedive.com/explore`)
            to:
              type: array
              description: Other indicators that this indicator redirects to.
              items:
                type: object
                properties:
                  iid:
                    type: integer
                    description: Unique identifier of other indicator.
                  indicator:
                    type: string
                    description: |
                      Value for other indicator.

                      May be:

                      - a domain name (e.g., `microsoft.com`)
                      - an IP address (e.g., `8.8.8.8`)
                      - a URL (e.g., `https://pulsedive.com/explore`)
        threats:
          type: array
          description: Known threats associated with this indicator.
          items:
            type: object
            properties:
              tid:
                type: integer
                description: Unique identifier of the threat.
              name:
                type: string
                description: Name of the threat.
                example: Zeus
              category:
                type: string
                description: Category assigned to the threat.
                example: malware
              risk:
                type: string
                description: Risk level associated with the threat.
                enum:
                  - retired
                  - none
                  - unknown
                  - very low
                  - low
                  - medium
                  - high
                  - critical
              stamp_linked:
                type: string
                format: sql-date-time
                pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                description: >
                  Timestamp when the threat was linked to this indicator.
                  24-hour format, UTC time zone.
                example: '2025-05-19 14:23:45'
        feeds:
          type: array
          description: Threat intelligence feeds that reference this indicator.
          items:
            type: object
            properties:
              fid:
                type: integer
                description: Unique identifier for the feed.
                nullable: false
              name:
                type: string
                description: Name of the feed.
                example: Zeus Bad Domains
              category:
                type: string
                description: Category assigned to the feed.
                example: malware
              organization:
                type: string
                description: Organization that provides the feed.
                example: abuse.ch
              pricing:
                type: string
                description: Pricing tier of the feed.
                example: free
              stamp_linked:
                type: string
                format: sql-date-time
                pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                description: >
                  Timestamp when the feed was linked to this indicator. 24-hour
                  format, UTC time zone.
                example: '2025-05-19 14:23:45'
        comments:
          type: array
          description: Comments submitted by Pulsedive contributors for this indicator.
          items:
            type: object
            properties:
              cid:
                type: integer
                description: Unique identifier for the comment.
                nullable: false
              username:
                type: string
                description: Username of the comment's author.
                example: sherd
              title:
                type: string
                description: Job title of the comment's author.
                example: Founder
              comment:
                type: string
                description: Text content of the comment.
                example: Have you seen our Pro tier? 😎
              stamp_added:
                type: string
                format: sql-date-time
                pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                description: >
                  Timestamp when the comment was created. 24-hour format, UTC
                  time zone.
                example: '2025-05-19 14:23:45'
              stamp_updated:
                type: string
                format: sql-date-time
                pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                description: >
                  Timestamp when the comment was last modified. 24-hour format,
                  UTC time zone.
                example: '2025-05-19 14:23:45'
              uid:
                type: integer
                description: |
                  Unique identifier for the user who created the comment.
                  Visible to only the user who submitted the comment.
        attributes:
          type: object
          description: Technical metadata observed for this indicator.
          properties:
            port:
              type: array
              description: List of ports open/in use.
              items:
                type: string
                example:
                  - '443'
                  - '80'
            protocol:
              type: array
              description: List of network protocols in use.
              items:
                type: string
                example:
                  - HTTP
                  - HTTPS
            technology:
              type: array
              description: List of technologies identified.
              items:
                type: string
                example:
                  - Apache
                  - jQuery
        properties:
          type: object
          description: >-
            Detailed sub-properties for this indicator, grouped by type or data
            source.
          properties:
            geo:
              type: object
              description: Geolocation details linked to this indicator.
              properties:
                countrycode:
                  type: string
                  description: Two-letter ISO country code.
                  example: US
                region:
                  type: string
                  description: State or region.
                  example: CA
                country:
                  type: string
                  description: Full country name.
                  example: United States of America
                address:
                  type: string
                  description: Street address.
                  example: 221 Lombard Street
                zip:
                  type: string
                  description: Postal or ZIP code.
                  example: '94102'
                city:
                  type: string
                  description: City or municipality.
                  example: San Francisco
                org:
                  type: string
                  description: Name of the associated organization.
                  example: Pulsedive
            whois:
              type: object
              description: >
                Collection of data sourced from WHOIS records and
                registrar-specific extensions to the base WHOIS schema, along
                with supplemental fields provided by Pulsedive (identified by a
                `++` prefix). May include details related to the domain, its
                registrar, and related contacts.


                Standard WHOIS data appears as key-value pairs, where each key
                matches a field name from the record and its value contains the
                corresponding content. Fields with multiple values are
                represented as arrays of strings.


                Pulsedive's supplemental fields do not appear in the original
                source data. These values are derived from raw data or parsed
                from related sources to provide additional context.
              properties:
                ++abuse:
                  type: string
                  description: Email address to report abuse related to the domain.
                  example: abuse-complaints@squarespace.com
                ++email:
                  type: array
                  description: >-
                    List of email addresses associated with the domain
                    registration. May include technical, administrative, or
                    contact emails.
                  items:
                    type: string
                  example:
                    - username1@organization1.org
                    - username2@organization1.org
                    - username@organization2.org
                ++expires:
                  type: string
                  format: sql-date-time
                  pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                  description: >
                    Timestamp when the domain's registration is set to expire.
                    24-hour format, UTC time zone.

                    Normalizes the ISO date in `registrar registration
                    expiration date`.
                  example: '2025-05-19 14:23:45'
                ++gdpr:
                  type: string
                  description: >
                    Indicates whether the domain's WHOIS data is restricted
                    under the General Data Protection Regulation (GDPR).


                    When set to `1`, the data is subject to GDPR restrictions.

                    When set to `0`, the data is not restricted by GDPR.
                  enum:
                    - '0'
                    - '1'
                ++phone:
                  type: array
                  description: >-
                    List of phone numbers associated with the domain
                    registration. May include technical, administrative, or
                    contact phone numbers.
                  items:
                    type: string
                  example:
                    - +1.646-693-5324
                ++privacy:
                  type: string
                  description: |
                    Indicates whether WHOIS privacy protection is enabled.

                    When set to `1`, privacy protection is enabled.
                    When set to `0`, privacy protect is not enabled.
                  enum:
                    - '0'
                    - '1'
                ++registered:
                  type: string
                  format: sql-date-time
                  pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                  description: >
                    Timestamp when the domain was initially registered. 24-hour
                    format, UTC time zone.

                    Normalizes the ISO date in `creation date`.
                  example: '2025-05-19 14:23:45'
                ++registrant:
                  type: array
                  description: >-
                    Supplementary list of registrant names. Derived from
                    `registrant name` and `registrant organization`.
                  items:
                    type: string
                  example:
                    - Zero Cool
                    - Titan Digital
                ++registrar:
                  type: string
                  description: Name of the registrar managing the domain registration.
                  example: Squarespace Domains II LLC
                ++updated:
                  type: string
                  format: sql-date-time
                  pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                  description: >
                    Timestamp when the domain's WHOIS record was last updated.
                    24-hour format, UTC time zone.

                    Normalizes the ISO date in `updated date`.
                  example: '2025-05-19 14:23:45'
              additionalProperties:
                anyOf:
                  - type: string
                    description: >
                      Dynamic key-value pairs representing WHOIS data field
                      names and values.


                      Each `{key}` represents the name of a WHOIS data field.
                      The `{value}` string contains the content retrieved for
                      that field.
                  - type: array
                    items:
                      type: string
                      description: >
                        Dynamic key-value pairs representing WHOIS data field
                        names and values.


                        Each `{key}` represents the name of a WHOIS data field.
                        The `{value}` array contains multiple pieces of content
                        retrieved for that field.
                example:
                  registrant organization: Titan Digital
                  name server:
                    - ns1.example.com
                    - ns2.example.com
              example:
                ++abuse: abuse-complaints@squarespace.com
                ++email:
                  - username1@organization1.org
                ++expires: '2025-05-19 14:23:45'
                ++gdpr: '0'
                ++phone:
                  - +1.646-693-5324
                ++privacy: '0'
                ++registered: '2025-05-19 14:23:45'
                ++registrant:
                  - Zero Cool
                  - Titan Digital
                ++registrar: Squarespace Domains II LLC
                ++updated: '2025-05-19 14:23:45'
                registrant organization: Titan Digital
                name server:
                  - ns1.example.com
                  - ns2.example.com
            http:
              type: object
              description: >
                Collection of data extracted from the HTTP response and headers,
                along with supplemental fields provided by Pulsedive (identified
                by a `++` prefix). May include details related to the result,
                server, content, caching, security, redirects, timing, or custom
                headers. Collected during active scanning.


                Standard HTTP response data appears as key-value pairs, where
                each key matches a header name and its value contains the
                corresponding content. Fields with multiple values are
                represented as arrays of strings.


                Pulsedive's supplemental fields do not appear in the original
                source data. These values are derived from raw data or parsed
                from related sources to provide additional context.
              properties:
                ++code:
                  type: string
                  description: >-
                    Numeric portion of the HTTP status code, indicating the
                    result of the HTTP request.
                  example: '200'
                ++status:
                  type: string
                  description: >-
                    Text portion of the HTTP status code, indicating the result
                    of the HTTP request.
                  example: OK
                ++content-type:
                  type: string
                  description: MIME type of the page, excluding parameters.
                  example: text/html
                ++base:
                  type: string
                  description: Base URL or origin context.
                  example: https://pulsedive.com/
                ++target:
                  type: string
                  description: >-
                    Target URL of the scan. For example, if you scan
                    `google.com`, the target URL will be `http://google.com`.
                  example: http://pulsedive.com/
                ++redirect:
                  type: string
                  description: >-
                    Final URL of the scan, after any redirects or automatic
                    HTTPS upgrades (HSTS).
                  example: https://pulsedive.com/
              additionalProperties:
                anyOf:
                  - type: string
                    description: >
                      Dynamic key-value pair representing a single HTTP header
                      and its value.


                      Each `{key}` represents the name of the HTTP header. The
                      `{value}` string contains the content returned in the
                      response.
                  - type: array
                    items:
                      type: string
                      description: >
                        Dynamic key-value pair representing a single HTTP header
                        and its value.


                        Each `{key}` represents the name of the HTTP header. The
                        `{value}` array contains the content returned for
                        headers that appear multiple times in the response.
                example:
                  Content-Type: application/json
                  Set-Cookie:
                    - sessionid=abc123; Path=/; Secure
                    - userid=42; Path=/; HttpOnly
              example:
                ++code: '200'
                ++status: OK
                ++content-type: text/html
                ++base: https://pulsedive.com/
                ++target: http://pulsedive.com/
                ++redirect: https://pulsedive.com/
                Content-Type: application/json
                Set-Cookie:
                  - sessionid=abc123; Path=/; Secure
                  - userid=42; Path=/; HttpOnly
            ssl:
              type: object
              description: >
                Collection of data extracted from the SSL/TLS certificate
                presented during a handshake. May include information about
                ownership and identity, issuing authority, certificate
                lifecycle, and technical fingerprinting. Collected during active
                scanning.
              properties:
                subject:
                  type: string
                  description: Entity to which the certificate was issued.
                  example: /CN=pulsedive.com
                domain:
                  type: array
                  description: >-
                    Primary domain name associated with the certificate,
                    typically from the Common Name (CN) or Subject Alternative
                    Name (SAN).
                  items:
                    type: string
                    example:
                      - pulsedive.com
                      - www.pulsedive.com
                version:
                  type: string
                  description: Version of the X.509 standard used by the certificate.
                  example: v3
                org:
                  type: string
                  description: >-
                    Common Name (CN) of the specific certificate authority that
                    signed the certificate, extracted from the issuer field.
                  example:
                    - WE1
                    - R11
                ip:
                  oneOf:
                    - type: string
                      format: ipv4
                    - type: string
                      format: ipv6
                  description: >-
                    IP address of the server presenting the certificate, if
                    resolved.
                  example:
                    - 162.159.36.1
                    - 2606:4700:4700::1001
                issuer:
                  type: string
                  description: >-
                    Full Distinguished Name (DN) of the Certificate Authority
                    (CA) that issued the certificate. Includes components like
                    country (C), organization (O), and common name (CN).
                  example:
                    - /C=US/O=Google Trust Services/CN=WE1
                    - /C=US/O=Let's Encrypt/CN=R11
                expires:
                  type: string
                  format: sql-date-time
                  pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                  description: >
                    Timestamp when the certificate expires. After this date, the
                    certificate is no longer valid. 24-hour format, UTC time
                    zone.
                  example: '2025-05-19 14:23:45'
                fingerprint:
                  type: string
                  description: >-
                    Hash of the certificate used to uniquely identify the
                    certificate and detect duplicates or known bad certs.
                  example: >-
                    c47649d46db4cf725334942920ccb076b331a5a60dc3f58608bbf72512d222cd
                valid:
                  type: string
                  format: sql-date-time
                  pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                  description: >
                    Timestamp when the certificate becomes valid. 24-hour
                    format, UTC time zone.
                  example: '2025-05-19 14:23:45'
                email:
                  type: string
                  description: >-
                    Email address listed in the certificate's `subject` or
                    `issuer` fields.
                  example: username@pulsedive.com
            dns:
              type: object
              description: >
                Collection of DNS records gathered from public resolvers. May
                include details related to domain ownership, mail exchange
                servers, name servers, and other DNS configurations. Collected
                during active and passive scanning.


                Data appears as key-value pairs, where each key represents a DNS
                record type and its value contains the corresponding data.
                Fields with multiple values are represented as arrays of
                strings.
              additionalProperties:
                anyOf:
                  - type: string
                    description: >
                      Dynamic key-value pair representing a single DNS record
                      type and its value.


                      Each `{key}` represents the DNS record type. The `{value}`
                      string contains the response associated with that type.
                  - type: array
                    items:
                      type: string
                      description: >
                        Dynamic key-value pair representing a single DNS record
                        type and its value.


                        Each `{key}` represents the DNS record type. The
                        `{value}` array contains the response associated with
                        types that appear multiple times in the response.
              example:
                a: 142.250.190.14
                aaaa: 2607:f8b0:4004:c1b::8e
                mx: alt3.aspmx.l.google.com
                ns:
                  - ns1.digitalocean.com
                  - ns2.digitalocean.com
                  - ns3.digitalocean.com
                txt:
                  - v=spf1 include:_spf.google.com ~all
                  - google-site-verification=abc123
            meta:
              type: object
              description: >-
                Website metadata extracted from the HTML <head> tag. May include
                standard WC3 meta tags (e.g., charset), SEO and crawling tags
                (e.g., description, robots), social media platform meta tags
                (e.g., twitter:card or og:card), or custom meta tags. Each key
                represents a meta tag type, and its corresponding value is the
                value retrieved from that meta tag.Collected during active
                scanning.
              properties:
                ++title:
                  type: string
                  description: >-
                    Title of the website collected from the HTML <title> tag in
                    the <head> tag.
                  example: Threat Intelligence - Pulsedive
              additionalProperties:
                anyOf:
                  - type: string
                    description: >
                      Dynamic key-value pairs representing website metadata tags
                      and values.


                      Each `{key}` represents the name of metadata tag. The
                      `{value}` string contains the value retrieved for that
                      tag.
                  - type: array
                    items:
                      type: string
                      description: >
                        Dynamic key-value pairs representing website metadata
                        tags and values.


                        Each `{key}` represents the name of a metadata tag. The
                        `{value}` array contains multiple values retrieved for
                        that tag.
                example:
                  Content-Type: text/html; charset=UTF-8
                  og:image:
                    - https://example.com/image1.jpg
                    - https://example.com/image2.jpg
              example:
                ++title: Threat Intelligence - Pulsedive
                Content-Type: text/html; charset=UTF-8
                og:image:
                  - https://example.com/image1.jpg
                  - https://example.com/image2.jpg
            banners:
              type: object
              description: >
                Mapping of port numbers to service banner strings, collected
                during active scanning.


                Each `{key}` matches a port number. The corresponding value may
                be a string or an array of strings, depending on how many
                banners were retrieved for that port.
              additionalProperties:
                anyOf:
                  - type: string
                    description: >
                      Each `{key}` matches a port number. The `{value}` string
                      contains the banner retrieved for that port.
                  - type: array
                    items:
                      type: string
                    description: >
                      Each `{key}` matches a port number. The `{value}` array
                      contains multiple banners retrieved for that port.
              example:
                '22': |
                  SSH-2.0-OpenSSH_7.4
                '143':
                  - >
                    * OK [CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED] Dovecot
                    ready.
                  - |
                    * PREAUTH [CAPABILITY IMAP4rev1 SASL-IR] Logged in as user
            cookies:
              type: object
              description: >
                Mapping of HTTP cookies set by this indicator, collected during
                active scanning.


                Each `{key}` represents the name of a cookie. The corresponding
                value may be a string or an array of strings, depending on how
                many pieces of content were retrieved for that cookie.
              additionalProperties:
                anyOf:
                  - type: string
                    description: >
                      Each `{key}` represents the name of a cookie. The
                      `{value}` string contains the content retrieved for that
                      cookie.
                  - type: array
                    items:
                      type: string
                    description: >
                      Each `{key}` represents the name of a cookie. The
                      `{value}` array contains multiple pieces of content
                      retrieved for that cookie.
              example:
                _ga: GA1.1.1991921685.1744247816
                _ga_g550td8bzn: GS1.1.1744247869.1.0.1744247869.0.0.0
                token:
                  - abc
                  - def
            dom:
              type: object
              description: >-
                Data related to the Document Object Model (DOM) of this
                indicator. Collected during active scanning.
              properties:
                screenshot:
                  type: string
                  format: url
                  description: URL of a screenshot of the loaded page.
                  example: >-
                    https://sandbox.pulsedive.com/screenshots/4179fbe377b84604ba4eaee47f5de9d2.jpeg
        links:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/LinkedIndicator'
    LinkedIndicator:
      type: object
      description: An indicator linked to the queried indicator.
      properties:
        iid:
          type: integer
          description: Unique identifier of the linked indicator.
          example: 47936201
        indicator:
          type: string
          description: |
            Value of the linked indicator.

            May be:

            - a domain name (e.g., `microsoft.com`)
            - an IP address (e.g., `8.8.8.8`)
            - a URL (e.g., `https://pulsedive.com/explore`)
          example: ns-cloud-d4.googledomains.com
        type:
          type: string
          description: Type of the linked indicator.
          example: domain
        risk:
          type: string
          description: Risk level of the linked indicator.
          enum:
            - unknown
            - very low
            - low
            - medium
            - high
            - critical
            - retired
            - none
          example: none
        stamp_linked:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was linked. 24-hour format, UTC time
            zone.
          nullable: true
          example: '2024-01-20 15:30:00'
        summary:
          type: object
          description: >
            Dynamically-generated condensed summary of key information about the
            linked indicator. Structure varies by indicator type and available
            data. Examples of data that could be included: domain name,
            geolocation data, WHOIS data, threats, and feeds.
    ExploreIndicatorsResponse:
      description: >
        Response from an indicator search query. Contains an array of matching
        indicators and the effective query that was executed.
      $ref: '#/components/schemas/JSONResponse'
    JSONResponse:
      type: object
      description: >
        Response from an indicator search query. Contains an array of matching
        indicators and the effective query that was executed.
      properties:
        results:
          type: array
          description: >
            Array of indicators matching the search query. Each indicator
            includes core identification, risk assessment, and summary
            information.


            The structure of each indicator object varies based on available
            data. Common fields include indicator value, type, risk, timestamps,
            and associated threats/feeds.
          items:
            $ref: '#/components/schemas/IndicatorSummary'
        query:
          type: string
          description: >
            The effective query string that was executed. This reflects the
            parsed and processed version of your original query.


            Useful for debugging query syntax and understanding how Pulsedive
            interpreted your search.
          example: ioc=pulsedive.com or threat=ryuk
      example:
        results:
          - iid: 123
            indicator: pulsedive.com
            type: domain
            risk: none
            stamp_added: '2020-01-15 10:30:00'
            stamp_updated: '2025-05-19 14:23:45'
            stamp_seen: '2025-05-19 14:23:45'
            stamp_retired: null
            summary:
              properties:
                geo:
                  country: United States
                  countrycode: US
                dns:
                  a: 142.250.190.14
          - iid: 456
            indicator: malicious-domain.com
            type: domain
            risk: high
            stamp_added: '2024-03-20 08:15:00'
            stamp_updated: '2025-05-18 12:00:00'
            stamp_seen: '2025-05-18 12:00:00'
            stamp_retired: null
            summary:
              threats:
                - name: Ryuk
                  category: ransomware
        query: ioc=pulsedive.com or threat=ryuk
    CSVResponse:
      type: string
      description: >
        CSV-formatted results with headers. 


        The CSV includes:

        - Query metadata in comment lines (prefixed with `#`)

        - Column headers

        - Indicator data rows with fields like indicator, type, risk,
        timestamps, location data, and reference URLs
    STIXResponse:
      type: object
      description: >
        STIX 2.1 Bundle containing STIX objects from the search results, plus a
        custom Pulsedive extension object.


        Requires authentication.
      properties:
        type:
          type: string
          description: |
            Type of STIX object. This will always be `bundle`.
          enum:
            - bundle
          example: bundle
        id:
          type: string
          description: |
            Unique identifier for this bundle.
          pattern: >-
            ^bundle--[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
          example: bundle--b4b37873-9452-506a-ba2d-1ada2645edf3
        objects:
          type: array
          description: >
            Array of STIX 2.1 objects. The first two objects are always system
            objects, followed by query results:


            1. `identity`: Identifies the Pulsedive organization. Conforms to
            the STIX 2.1 specification for the [STIX Identity Domain
            Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_wh296fiwpklp).

            2. `extension-definition`: Defines Pulsedive custom extended
            properties for the STIX Indicator Domain Object.

            3. Query results: STIX objects that conform to the [STIX 2.1
            specification](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_nrhq5e9nylke).

                For indicators:
                - [STIX Indicator Domain Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_muftrcpnf89v), plus Pulsedive extended properties defined in the `extension-definition` object.

                For threats, the appropriate object:
                - [STIX Malware Domain Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_s5l7katgbp09)
                - [STIX Threat Actor Domain Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_k017w16zutw)
                - [STIX Campaign Domain Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_pcpvfz4ik6d6)
                - [STIX Attack Pattern Domain Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_axjijf603msy)
                - [STIX Tool Domain Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_z4voa9ndw8v)
                - [STIX Vulnerability Domain Object](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_q5ytzmajn6re)
          items:
            anyOf:
              - $ref: '#/components/schemas/PulsediveExtensionDefinition'
              - $ref: '#/components/schemas/PulsediveSTIXIndicator'
    PulsediveExtensionDefinition:
      type: object
      title: Pulsedive Indicator Extension
      properties:
        type:
          type: string
          description: >
            Type of STIX object. For the Pulsedive custom extension, this will
            always be `extension-definition`.
          enum:
            - extension-definition
          example: extension-definition
        id:
          type: string
          description: |
            Unique identifier for this extension definition.
          example: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
        name:
          type: string
          description: |
            Name of the extension.
          example: Pulsedive
        description:
          type: string
          description: |
            Explanation of what the extension does.
          example: >-
            Pulsedive is an analyst-centric threat intelligence platform built
            with on-demand scanning for live data, risk scoring to reduce false
            positives, and powerful integration capabilities for leveraging
            Pulsedive data inside your organization.
        schema:
          type: string
          description: |
            URL pointing to the JSON schema or documentation for this extension.
          example: https://pulsedive.com/api/taxii
        version:
          type: string
          description: |
            Version of the extension definition.
          example: 1.0.0
        extension_types:
          type: array
          description: >
            Type for the Pulsedive custom extension. Always
            `toplevel-property-extension`.
          items:
            type: string
          example: toplevel-property-extension
        extension_properties:
          type: array
          description: |
            Names of the custom properties this extension adds.
          items:
            type: string
            enum:
              - pulsedive_risk
              - pulsedive_risk_int
              - pulsedive_retired
              - pulsedive_retired_timestamp
              - pulsedive_retired_reason
        created:
          type: string
          format: date-time
          description: |
            Timestamp when this extension definition was created. UTC format.
          example: '2025-11-17T02:41:46.000Z'
        modified:
          type: string
          format: date-time
          description: >
            Timestamp when this extension definition was last modified. UTC
            format.
          example: '2025-11-17T02:41:46.000Z'
        created_by_ref:
          type: string
          description: >
            Unique Identifier of the Identity object that created this
            extension.
          example: identity--5c9fb347-238c-5b07-bae0-93fe6972689d
        spec_version:
          type: string
          description: |
            STIX specification version. Pulsedive uses 2.1.
          example: '2.1'
    PulsediveSTIXIndicator:
      title: Extended STIX Indicator Properties
      allOf:
        - type: object
        - $ref: '#/components/schemas/PulsediveIndicatorExtension'
    PulsediveIndicatorExtension:
      type: object
      properties:
        pulsedive_risk:
          type: string
          description: |
            Risk level assigned by Pulsedive's risk scoring algorithm.
          enum:
            - none
            - unknown
            - low
            - medium
            - high
            - critical
          example: none
        pulsedive_risk_int:
          type: integer
          description: >
            Numeric representation of the risk level for easier programmatic
            comparison and sorting.


            Options include: `-1` (`none`), `0` (`unknown`), `1` (`low`), `2`
            (`medium`), `3` (`high`), `4` (`critical`).
          enum:
            - -1
            - 0
            - 1
            - 2
            - 3
            - 4
          example: '2'
        pulsedive_retired:
          type: integer
          description: >
            Indicates whether the indicator is inactive or obsolete.


            An indicator is automatically retired if, in the past three months,
            it has not been:


            - Reported using the Seen button in the Pulsedive UI

            - Observed in any source feeds

            - Submitted through the Analyze section of the Pulsedive UI


            Pulsedive research can also retire indicators manually.


            When set to `1`, this indicator is retired.

            When set to `0`, this indicator is active.
          enum:
            - 0
            - 1
          example: '1'
        pulsedive_retired_timestamp:
          type: string
          format: date-time
          description: >
            Timestamp when the indicator was retired. UTC format. Only appears
            when retired.
          example: '2025-05-19T14:23:45.000Z'
        pulsedive_retired_reason:
          type: string
          description: |
            Explanation for why the indicator was retired.
          example: Domain no longer resolves.
    IndicatorSummary:
      type: object
      description: >
        Summary information for an indicator from Explore search results. 


        The exact structure varies based on indicator type and available data.
        This schema represents common fields, but additional fields may be
        present.
      properties:
        iid:
          type: integer
          description: |
            Unique identifier of the indicator.
          example: 123
        indicator:
          type: string
          description: |
            Value of the indicator.

            May be:

            - a domain name (e.g., `microsoft.com`)
            - an IP address (e.g., `8.8.8.8`)
            - a URL (e.g., `https://pulsedive.com/explore`)
            - a file hash (e.g., `d41d8cd98f00b204e9800998ecf8427e`)
          example: pulsedive.com
        type:
          type: string
          description: Type of the indicator.
          enum:
            - domain
            - ip
            - ipv6
            - url
            - hash
          example: domain
        risk:
          type: string
          description: Risk level of the indicator.
          enum:
            - unknown
            - none
            - low
            - medium
            - high
            - critical
            - retired
          example: none
        stamp_added:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was first added to Pulsedive. 24-hour
            format, UTC time zone.
          example: '2020-01-15 10:30:00'
        stamp_updated:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator record was last updated in Pulsedive.
            24-hour format, UTC time zone.
          example: '2025-05-19 14:23:45'
        stamp_seen:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was last reported or seen in feeds or
            user submissions in Pulsedive. 24-hour format, UTC time zone.
          nullable: true
          example: '2025-05-19 14:23:45'
        stamp_retired:
          type: string
          format: sql-date-time
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
          description: >
            Timestamp when the indicator was retired in Pulsedive, if
            applicable. 24-hour format, UTC time zone.
          nullable: true
          example: '2019-07-25 09:44:31'
        summary:
          type: object
          description: >
            Dynamically-generated condensed summary of key information about the
            indicator. 


            The structure varies based on indicator type and available data. May
            include properties (technical data), threats, feeds, and other
            contextual information.
          additionalProperties: true
          example:
            properties:
              geo:
                country: United States
                countrycode: US
              dns:
                a: 142.250.190.14
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Message describing the error that occurred, if available.
  responses:
    BadRequest:
      description: |
        Bad request. The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: |
        Unauthorized. Your API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: |
        Not found. The requested indicator could not be located.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: >
        Rate limit exceeded. Too many requests have been made in a short period
        of time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: |
        Server error. An unexpected problem occurred on our end.
        These errors are automatically reported to our team.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'