# Overview Source: https://docs.pulsedive.com/addon/overview Enrich web content with Pulsedive threat intelligence directly in your browser. The Pulsedive browser add-on brings threat intelligence to any website you visit. Highlight IPs, domains, URLs, or threat names in any webpage text to enrich them using Pulsedive's Community dataset. The add-on works without an account, API key, or paid plan. Creating a free account at pulsedive.com unlocks higher limits and additional capabilities. ## Installation The add-on is available for Chrome and Firefox. | Browser | Store | | - | - | | Chrome | [Chrome Web Store](https://chromewebstore.google.com/detail/pulsedive-threat-intellig/gdbemlfgncdmmljmkkcemfedbbfgghcp) | | Firefox | [Firefox Add-Ons](https://addons.mozilla.org/en-US/firefox/addon/pulsedive/) | > [!NOTE] > > To learn how to use the add-on effectively, visit [Usage](/addon/usage). ## Features The add-on supports a wide range of threat research workflows. Use it to enrich individual indicators, look up threats by name, or process thousands of indicators or threats at once. ### Indicator Highlighting Highlight text on any webpage to parse and refang a domain, IP address, or URL and enrich it with Pulsedive threat intelligence. From the add-on sidebar, run scans and pivot directly to Pulsedive for further investigation. ### Bulk Parsing Highlight text containing hundreds or thousands of observable entities to parse and refang them all at once. Download the results as a CSV file, or pass them to [Pulsedive Analyze](https://pulsedive.com/analyze/) for bulk enrichment. ### Threat Enrichment The add-on can retrieve threat information for any threat name or alias found in webpage text, including associated indicators, TTPs, latest news, and more. ### Auto-Popup The auto-popup is a sidebar that appears automatically when you highlight text containing supported observable entities. Triggering behavior depends on what you highlight: * **Single indicator:** The indicator must make up most of the highlighted text, which limits unintentional triggering. * **Multiple indicators:** The sidebar appears automatically if Bulk Parsing is enabled for the auto-popup. ### Add-On Button The add-on button in the browser toolbar provides direct access to enrichment, independent of most auto-popup settings: * **Text highlighted:** The add-on enriches the highlighted text regardless of auto-popup restrictions. * **No text highlighted:** The add-on displays information for the domain of the active browser tab. > [!NOTE] > > Threat enrichment is only available via the add-on button, not the auto-popup. # Usage Source: https://docs.pulsedive.com/addon/usage How to use the Pulsedive browser add-on to streamline threat research. The Pulsedive add-on keeps threat intelligence within reach wherever you work in the browser. Enrich indicators inline as you read, cutting down context switches in your workflow. These sections walk through the most common ways to put it to work. > [!NOTE] > > To install the add-on, visit [Overview](/addon/overview). ## Enriching Indicators While Browsing When you're reading a threat advisory, security blog, or research report, indicators appear as plain text scattered throughout the content. 1. Enable the auto-popup so the add-on identifies and highlights supported observable entities as you go, without copying anything manually. 2. Highlight any text containing a domain, IP address, or URL. The add-on sidebar opens with enrichment data from Pulsedive. 3. Run a passive or active scan, or pivot to Pulsedive for a deeper look. > [!TIP] > > If the auto-popup fires too aggressively on a particular site, visit [Muting Add-On Notifications](#muting-add-on-notifications). ## Processing a Large Set of Indicators When you have a block of text containing many indicators, from a log excerpt, a paste site, or a shared report, Bulk Parsing lets you process them all at once rather than one at a time. 1. Enable **Bulk Parsing** in the add-on settings. 2. Highlight the entire block of text. The add-on parses and refangs all observable entities it finds. 3. Download the full list as a CSV for use in other tools, or pass them to [Pulsedive Analyze](https://pulsedive.com/analyze/) for bulk enrichment. ## Researching a Threat Name When you come across a threat actor name, malware family, or campaign alias, look it up without navigating away from the page. 1. Highlight the exact name or alias in the page text. 2. Select the Pulsedive add-on button in the browser toolbar. The add-on retrieves a summary from Pulsedive's dataset and presents it in the sidebar. 3. Open the full threat profile on Pulsedive to explore associated indicators, TTPs, latest news, and more. > [!NOTE] > > Threat enrichment requires the add-on button. > It is not available via the auto-popup. ## Muting Auto-Popup The auto-popup is useful for active research, but it can become disruptive on sites where you don't need constant enrichment, such as internal tooling, ticketing systems, or sites with large volumes of known-good indicators. Use the mute options to reduce interruptions without disabling the add-on entirely. 1. Select the auto-popup sidebar on the site you want to mute. 2. Choose a muting option: * **Mute for 5 minutes:** Temporarily pauses the auto-popup, then restores it automatically. * **Mute for this site:** Disables the auto-popup on the current domain until you remove the exception. * **Disable the auto-popup:** Turns off the auto-popup across all sites. To undo any of these: 1. Select the add-on button in the browser toolbar. 2. Select the **Unmute** menu. To review and remove site exceptions, visit the add-on settings page. # Authentication Source: https://docs.pulsedive.com/api/authentication Securely authenticate your requests to Pulsedive’s API to enable seamless access to threat intelligence data. Pulsedive uses API key authentication to secure and manage access to its threat intelligence endpoints. We recommend including your API key with every request for the best performance and highest rate limits. While you can make requests without an API key, you will encounter much stricter [rate limits](/api/limits/). *** ## Get Your API Key **1. Access your Pulsedive account** Visit Pulsedive and [log in](https://pulsedive.com/login) to your account, or [register](https://pulsedive.com/register) for free. **2. Get your API key** Navigate to [Account](https://pulsedive.com/account), then locate the **API key** section to retrieve your unique key. ## Include the Key in Your Request Include your API key in the `key` parameter in your request: ```bash theme={null} # Replace the placeholder text with your Pulsedive API key curl "https://pulsedive.com/api/indicator.php \ ?indicator=1.1.1.1 \ &pretty=1 \ &key=" ``` *** ## Best Practices * **Keep your API key private**: Don't share it or commit it to source control. * **Use an API tier that fits your needs**: If you need elevated rate limits, upgrade your [API plan](https://pulsedive.com/about/api). * **Monitor your usage**: Check your API usage in the **Activity** section of your [Account page](https://pulsedive.com/account). # Query Language Source: https://docs.pulsedive.com/api/explore/query-language Learn Pulsedive's query language syntax for searching threat intelligence data. Use boolean logic, wildcards, and field-specific searches to find indicators by risk, type, attributes, and more. This syntax applies to searches made through the [`explore` endpoint](/api/explore/search/). The Pulsedive query language enables searching across our dataset with boolean logic and wildcards for precise discovery. ## Search Modes The explore endpoint supports two search modes, controlled by the `type` parameter: * **Indicator mode** (`type=indicators`, default): Search for indicators by value, type, risk, attributes, properties, and associated threats or feeds. * **Threat mode** (`type=threats`): Search for threats by name, alias, category, or associated indicator attributes. The search mode determines which dataset you are querying and which filters are available. All modes support the same [query syntax](#syntax). > [!NOTE] > > Feeds are not a separate search mode. > To search for indicators associated with specific feeds, use the `feed` search field in indicator mode (e.g., `feed=urlhaus`). ## Syntax Query terms follow a simple field-value structure for building search expressions: ```txt theme={null} [search field]=[value] ``` ## Search Fields Search fields let you target specific aspects of indicators and threats. ### Indicator Mode Fields These fields are available when searching indicators (`type=indicators`, default): | Search Field | Description | Example Query | | - | - | - | | `ioc` | Search by indicator value. Default field when no search field is specified. | `ioc=pulsedive.com` `ioc=pulsedive*` `1.1.1.1` | | `threat` | Filter by associated threat name or alias. | `threat=ryuk` `threat=*zeus*` | | `property` `[property type]` `[property name]` `[type].[name]` | Filter by indicator properties. | `dns.a=45.55.106.210` `meta=*pulsedive*` `content-type=text/html*` `ssl="*let's encrypt*"` | | `type` | Filter by indicator type. | `type=url` `type=domain,ip,ipv6` | | `seen` | Filter by Last Seen timestamp (UTC). | `seen=day` `seen=week` `seen=month` `seen=2020-01-01` `seen=2022-01-01+` `seen=2021-12-31-` `seen=2020-01-01-2020-12-31` | ### Threat Mode Fields These fields are available when searching threats (`type=threats`): | Search Field | Description | Example Query | | - | - | - | | `threat` | Search by threat name or alias. Default field when no search field is specified. | `threat=ryuk` `threat=*zeus*` `ryuk` | | `ioc` | Filter by associated indicator values. | `ioc=pulsedive.com` `ioc=pulsedive*` | | `category` | Filter by threat category. | `category=malware` `category=phishing,scam` | ### Fields Available in Both Modes These fields work in both indicator and threat mode: | Search Field | Description | Example Query | | - | - | - | | `feed` `source` | Filter by associated feed name or organization. | `feed=urlhaus` `feed=abuse.ch` | | `attribute` `[attribute type]` | Filter by indicator attributes. Includes ports, protocols, and technologies. | `port=443` `protocol=http*` `technology=apache` `port=80 and port=443` | | `risk` | Filter by risk level. | `risk=critical` `risk=low,medium` `risk=high+` `risk=low-` | | `active` `retired` | Filter by active or retired status. | `active=true` `retired=0` | ## Boolean Logic and Wildcards Combine search terms using logical operators and pattern matching for complex queries. Queries allow for `AND`, `OR`, and `NOT` operations. Wildcards are also allowed. If an operator is omitted between search terms, the default operation is `AND`. | Operation | Operator | Example Query | | - | - | - | | AND | `&`, `&&`, `and` | `pulsedive.com && type=domain` `pulsedive.com type=domain` | | OR | `\|`, `\|\|`, `or` | `google.com or pulsedive*` `(*pulsedive* and type=domain) \| threat=phishing` | | NOT | `!=` | `risk!=medium-` | | Wildcard | `*` | `*pulsedive*` | ## Escaping and Quotes Use escaping and quotes to handle special characters and spaces in your search terms. Since special characters like asterisks (`*`) and parentheses (`()`) might conflict with your intended query, you can escape them with a backslash (`\`). If your search field or search term has a space, you must wrap it in quotes (`"`). ## Examples These examples show how to specify search modes using the `type` parameter and construct queries with proper URI encoding. Search indicators (default): ```bash theme={null} # These are equivalent curl "https://pulsedive.com/api/explore.php?q=risk%3Dhigh" curl "https://pulsedive.com/api/explore.php?type=indicators&q=risk%3Dhigh" ``` Search threats: ```bash theme={null} curl "https://pulsedive.com/api/explore.php?type=threats&q=risk%3Dhigh" ``` Filter indicator types (within indicator mode): ```bash theme={null} # Note: type=domain is inside the query string (q parameter) curl "https://pulsedive.com/api/explore.php?q=type%3Ddomain%20and%20risk%3Dhigh" ``` > [!NOTE] > > The mode parameter `type` is separate from the query field `type=`. > The parameter controls which dataset to search (indicators or threats), while the query field filters indicators by their type (e.g., domain, IP, URL). Combining both the parameter and the query field looks like: ```bash theme={null} # Search indicator mode, filter by domain type only curl "https://pulsedive.com/api/explore.php?type=indicators&q=type%3Ddomain%20and%20risk%3Dhigh" ``` # Search Dataset Source: https://docs.pulsedive.com/api/explore/search /api/scan-explore.yaml get /api/explore.php 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/). # Get Feed by ID Source: https://docs.pulsedive.com/api/feed/get-by-id /api/feed/feed-by-id.yaml get /api/feed.php Retrieve detailed threat intelligence information for a specific feed by looking up the feed's unique identifier. # Get Feed by Name and Organization Source: https://docs.pulsedive.com/api/feed/get-by-name-organization /api/feed/feed-by-name-and-org.yaml get /api/feed.php Retrieve detailed threat intelligence information for a specific feed by looking up the feed's unique identifier. # Get Linked Indicators Source: https://docs.pulsedive.com/api/feed/get-linked-indicators /api/feed/feed-get-links.yaml get /api/feed.php Retrieve indicators linked to a specific feed. # Get Indicator by ID Source: https://docs.pulsedive.com/api/indicator/get-by-id /api/indicator/indicator-by-id.yaml get /api/indicator.php Retrieve detailed threat intelligence information for a specific indicator by looking up the indicator's unique identifier. # Get Indicator by Value Source: https://docs.pulsedive.com/api/indicator/get-by-value /api/indicator/indicator-by-value.yaml get /api/indicator.php Retrieve detailed threat intelligence information for a specific indicator by looking up the indicator's value. To query links and properties, retrieve the indicator by ID instead. # Get Indicator Links or Properties Source: https://docs.pulsedive.com/api/indicator/get-links-properties /api/indicator/indicator-get-links-properties.yaml get /api/indicator.php Retrieve links or properties for a specific indicator. # Rate Limits Source: https://docs.pulsedive.com/api/limits Understand Pulsedive API rate limits, monitor usage with HTTP headers, and handle 429 errors. The Pulsedive API implements rate limits to ensure reliable service for all users. Your rate limits depend on your API plan and appear on your [Account page](https://pulsedive.com/account). ### Plan-Based Limits Rate limits vary based on your subscription tier, with higher plans offering increased capacity for production use. * **Free accounts**: Basic limits with requests limited per second, day, and month. * **[Pro API](https://pulsedive.com/about/pro)**: Increased limits suitable for individual professionals and hobbyists. * **[Commercial API](https://pulsedive.com/about/api)**: Increased limits for commercial environments. Higher-tier plans have soft limits. * **[Enterprise](https://pulsedive.com/about/enterprise)**: No rate limits. ### What are Soft Limits? Soft limits don't block your requests with error codes. However, if you consistently exceed your plan's limits, we may reach out about upgrading [your plan](https://pulsedive.com/about/api) or reducing your request frequency. ### Rate Limit Headers Each response includes HTTP headers showing your remaining requests for each period: ```text theme={null} X-Requests-Remaining-Second: 1 X-Requests-Remaining-Day: 9 X-Requests-Remaining-Month: 249 ``` > [!NOTE] > > Missing headers indicate no rate limit for that time period. > Note that headers may not appear in `429` error responses, so check both headers and status codes to monitor your usage. ### Rate Limit Exceeded When you exceed your limits, you receive an HTTP `429` status code along with a response like: ```json theme={null} { "error": "API rate limit exceeded: 1 requests per second. Visit pulsedive.com\\/api to view limits and upgrade your plan." } ``` You'll also receive this error code when queries exceed other limits, such as the maximum result count for searches with the [`explore` endpoint](/api/explore/search) (varies by plan). *** Ready to get started? Check out our [Pro](https://pulsedive.com/about/pro) and [API](https://pulsedive.com/about/api) plans for higher limits, or dive into the endpoints. # API Reference Source: https://docs.pulsedive.com/api/overview Access comprehensive threat intelligence through Pulsedive's API. Search indicators, scan for threats, retrieve feed data, and automate security workflows with the same endpoints that power our web interface. ## Welcome to the Pulsedive API! The Pulsedive platform UI performs requests to the same endpoints you will access programmatically. This means that in most cases, you can use the API to fetch the same data and perform the same functions as the [web interface](https://pulsedive.com/). We have designed the API to be flexible and comprehensive, but if you have questions or need features we haven't covered yet, please [contact us](https://pulsedive.com/contact)! ## Endpoints Direct all API requests to these paths: **/api/indicator.php** [Look up threat intelligence for specific indicators](/api/indicator/overview/) like domains and IP addresses. **/api/analyze.php** [Scan indicators](/api/scan/overview/) on-demand to gather threat intelligence without storing them permanently. **/api/explore.php** [Search across Pulsedive's database](/api/explore/overview/) using flexible queries to find indicators or threats that match your criteria. **/api/threat.php** [Get information about threats](/api/threat/overview/) like malware families, adversary groups, and campaigns. **/api/feed.php** [Access curated threat intelligence collections](/api/feed/overview/) from security organizations and research projects. # Pagination Source: https://docs.pulsedive.com/api/pagination Retrieve large datasets efficiently with automatic page breaks. * Pagination only applies when requesting linked indicators from threats or feeds. Other API endpoints do not use pagination. * Page limits per request vary by plan: * Free: 1 * Pro: 2 * Team: 4 * Business/Custom: 10 When working with large datasets, pagination helps you retrieve manageable chunks of data instead of overwhelming responses. The Pulsedive API automatically breaks large result sets into pages when you request linked indicators from threats or feeds. *** ## How Pagination Works When your request returns a large number of results, the Pulsedive API automatically splits the response into pages and includes helpful navigation fields: * `page_current`: Shows which page you are currently viewing (starts at `0`) * `page_next`: Tells you the next page number to request (only appears when more pages are available) The first page of a paginated response looks like this: ```json theme={null} { "page_current": 0, "page_next": 1, "results": [ { "iid": 918421, "indicator": "185.220.100.255", "type": "ip", "risk": "low", "stamp_linked": "2018-11-18 11:46:55", "summary": { "properties": { ... } } }, ... ] } ``` > [!NOTE] > > If your results fit on a single page, you won't receive the `page_current` and `page_next` fields. ## Retrieving Additional Pages To get the next page of results, make the same request and add a `page` parameter with the value from `page_next`. Keep requesting subsequent pages until `page_next` disappears from the response—this means you have reached the end of the data. > [!NOTE] > > Each pagination request counts toward your API rate limits. > Plan your requests accordingly when working with large datasets. ### Example Workflow This walkthrough demonstrates how to retrieve all linked indicators from a feed using pagination. **1. Make your initial request** This example uses these parameters: ```json theme={null} { "fid": "19", "get": "links", "pretty": "1", "key": "" } ``` Make a request to the [`feed.php` endpoint](/api/feed/get-by-id/): ```bash theme={null} curl "https://pulsedive.com/api/feed.php \ ?fid=19 \ &get=links \ &pretty=1 \ &key=" ``` **2. Check the response for pagination fields** The results include `page_current` and `page_next` keys: ```json theme={null} { "page_current": 0, "page_next": 1, "results": [ { "iid": 918421, "indicator": "185.220.100.255", "type": "ip", "risk": "low", "stamp_linked": "2018-11-18 11:46:55", "summary": { "properties": { ... } } }, ... ] } ``` **3. Request the next page** Using the `page_next` value, request the next page with the `page` parameter: ```json theme={null} { "fid": "19", "get": "links", "pretty": "1", "key": "", "page": "1" } ``` ```bash theme={null} curl "https://pulsedive.com/api/feed.php \ ?fid=19 \ &get=links \ &pretty=1 \ &page=1 \ &key=" ``` **4. Continue until `page_next` is no longer included** When results are exhausted, only `page_current` appears: ```json theme={null} { "page_current": 2, "results": [ { "iid": 95352, "indicator": "191.20.101.211", "type": "domain", "risk": "medium", "stamp_linked": "2021-04-23 05:22:12", "summary": { "properties": { ... } } }, ... ] } ``` *** ## Troubleshooting Find answers to common questions about working with paginated responses. ### Can I jump to a specific page? While you can technically request any page number, we recommend following the sequence provided by `page_next`. Skipping ahead or accessing pages out of order can lead to inconsistent results, especially if the dataset has changed between requests. ### Can I go back to a previous page? Paging works in a forward direction only. To start over, make your original request again (without a `page` parameter) to get page 0. ### How do I know when I've retrieved all the data? You have reached the final page of results when the API response no longer includes a `page_next` value. # Quickstart Source: https://docs.pulsedive.com/api/quickstart Jump into Pulsedive’s powerful threat intelligence. This quickstart guide walks you through getting your API key, authenticating your first request, and retrieving data--all in under five minutes. No fluff, all action. ## Before You Begin To complete this quickstart, you will need: * **An active Pulsedive account**: [Sign up for free!](https://pulsedive.com/register) * A simple command-line tool like `curl` or your preferred HTTP client. > [!NOTE] > > Although you can access our API without an API key, using an API key gives you higher rate limits and smoother access to Pulsedive’s data. > You can [find your API key](https://pulsedive.com/account) in your account dashboard. *** ## Fetch Indicator Data Query the [`/indicator.php` endpoint](/api/indicator/overview/) by indicator value. This is one of the most common calls users make. ```bash theme={null} curl "https://pulsedive.com/api/indicator.php \ ?indicator=1.1.1.1 \ &pretty=1 \ &key=" ``` You'll receive detailed threat intelligence on the indicator, including risk scores, associated threats, and detailed scan data. *** ## Use Explore to Search Across Data Need to search across multiple indicators? Use the [`/explore.php` endpoint](/api/explore/overview/) with a query string. ```bash theme={null} curl "https://pulsedive.com/api/explore.php \ ?q=ioc=*evil* \ &limit=5 \ &pretty=1 \ &key=" ``` This returns up to five results matching your pattern, including filtering options like risk, type, and threat. To learn more about query syntax, operators, and wildcards, visit [Query Language](/api/explore/query-language/). *** ## Scan and Enrich an Indicator Want deeper insight? Request enrichment and scoring for an indicator using the [`/analyze.php` endpoint](/api/scan/overview/). **1. Initiate a scan** Request enrichment and scoring for your indicator. This tells Pulsedive to gather threat intelligence, generate insights, and perform risk scoring. ```bash theme={null} # Scan for passive (non-intrusive) analysis curl "https://pulsedive.com/api/analyze.php \ ?value=evil.com \ &probe=0 \ &pretty=1 \ &key=" ``` > [!TIP] > > Passive scans (`probe=0`) collect data without direct contact (WHOIS, DNS). > You can also request an active scan (`probe=1`) for comprehensive intelligence, but with noisier, direct contact. > [!TIP] > > By default, Pulsedive performs enrichment on new indicators without saving the indicator. > To save it to Pulsedive's database, add `submit=1` to your request. > Existing indicators are always updated with fresh scan results. You will receive a response like: ```json theme={null} { "success": "Added request to queue.", "sid": 2100188, "qids": [ { "indicator": "evil.com", "qid": 2100254203 } ] } ``` Your request is added to the queue immediately, but processing happens asynchronously in the background. **2. Poll for results** Use the returned queue ID (`qid`) to check for results: ```bash theme={null} curl "https://pulsedive.com/api/analyze.php \ ?qid=123456 \ &pretty=1 \ &key=" ``` *** ## What's Next? Once you're authenticated and have your first API responses: * Dive deeper into indicators: Try [retrieving indicator links or properties](/api/indicator/get-links-properties/) or use the [`historical`](/api/indicator/get-by-value#parameter-historical) and [`schema`](/api/indicator/get-by-value#parameter-schema) parameters to customize your results. * Explore other endpoints: Fetch [threat](/api/threat/get-by-name/) or [feed](/api/feed/get-by-name-organization/) data to expand your threat intelligence coverage. * For smoother development, check out [community libraries](/libraries/). # Responses Source: https://docs.pulsedive.com/api/responses Understand Pulsedive API response formats, HTTP status codes, and error handling. The Pulsedive API returns consistent, predictable responses to help you build reliable integrations. ## Response Format All API responses use JSON format for straightforward parsing and integration. ## Successful Responses Successful requests return predictable patterns with clear status indicators. When your request succeeds, you receive an HTTP `200` status code along with the requested data. Many successful responses also include a `success` parameter, though this parameter doesn't appear across all endpoints. ## Error Responses When requests fail, the API provides clear error messages to help you troubleshoot and resolve issues. When something goes wrong, the API returns a JSON object with an `error` field explaining what happened. For example, a request with these parameters: ```json title="GET request to /api/indicator.php with parameters" theme={null} { "iid": "-1", "pretty": "1" } ``` Returns this error: ```json title="404 Indicator not found" theme={null} { "error": "Indicator not found." } ``` ## HTTP Status Codes The API uses standard HTTP conventions to communicate result outcomes. ### Success Codes This code confirms your request completed successfully: * `200`: Request succeeded and data is returned. ### Client Error Codes These codes indicate issues with your request that you can resolve by adjusting parameters or authentication: * `400`: Bad request. Review your parameters or request format. * `401`: Unauthorized. Check your API key or permissions. * `404`: Not found. The requested resource doesn't exist. * `429`: [Rate limit](/api/limits/) exceeded. Wait before retrying or upgrade your plan for higher limits. ### Server Error Codes These codes indicate temporary issues on our end that resolve automatically: * `500`: Internal server error. We have been automatically notified and are investigating. # Add Indicator to the Queue Source: https://docs.pulsedive.com/api/scan/add /api/scan-explore.yaml post /api/analyze.php Add an indicator to the scanning queue and receive a queue ID, so you can poll for results. # Poll for Scan Results Source: https://docs.pulsedive.com/api/scan/poll /api/scan-explore.yaml get /api/analyze.php 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.) # Get Threat by ID Source: https://docs.pulsedive.com/api/threat/get-by-id /api/threat/threat-by-id.yaml get /api/threat.php Retrieve detailed threat intelligence information for a specific threat by looking up the threat's ID. # Get Threat by Name Source: https://docs.pulsedive.com/api/threat/get-by-name /api/threat/threat-by-name.yaml get /api/threat.php Retrieve detailed threat intelligence information for a specific threat by looking up the threat's name. To query links, retrieve the threat by ID instead. # Get Linked Indicators Source: https://docs.pulsedive.com/api/threat/get-linked-indicators /api/threat/threat-get-links.yaml get /api/threat.php Retrieve indicators linked to a specific threat. To create risk breakdowns, use the `summary` parameter with the `splitrisk` parameter. This will split out indicator counts by risk level. # Pulsedive Documentation Source: https://docs.pulsedive.com/index Find everything you need to look up indicators, investigate threats, and integrate Pulsedive into your detection and response workflows. ## Understand the Data > **[How Pulsedive Collects Data](/model/collection)** > > Learn how Pulsedive ingests, enriches, and retires threat intelligence. > **[Data Model](/model/overview)** > > Understand the core objects — indicators, threats, and feeds — and how they relate. ## Query the API > **[Quickstart](/api/quickstart)** > > Make your first API call in minutes. > **[API Reference](/api/indicator/overview)** > > Look up indicators, threats, and feeds; scan IOCs; and explore the Pulsedive dataset. ## Export Intelligence > **[Bulk Export](/export/overview)** > > Export large datasets as CSV or via TAXII for offline analysis and pipeline integration. > **[STIX/TAXII](/taxii/overview)** > > Consume Pulsedive data as STIX 2.1 objects over a TAXII 2.1 server. ## Integrate > **[Libraries](/libraries)** > > Community-maintained client libraries for working with the Pulsedive API. > **[Browser Add-on](/addon)** > > Highlight indicators and threat names on any webpage to enrich them with Pulsedive intelligence directly in your browser. # Get API Roots Source: https://docs.pulsedive.com/taxii/api-root/get /taxii/api.yaml get /taxii2 Get information about available API roots and server capabilities. # Get Collections Source: https://docs.pulsedive.com/taxii/collection/get /taxii/api.yaml get /taxii2/api/collections Get information about all [available collections](/taxii/collection/overview#available-collections) in the API root. Collections contain the STIX objects you can download from Pulsedive's TAXII server. # Get Objects Source: https://docs.pulsedive.com/taxii/object/get /taxii/api.yaml get /taxii2/api/collections/{collectionID}/objects Fetch STIX objects from a specific collection with optional filtering and pagination. # Account Management Source: https://docs.pulsedive.com/troubleshoot/common-issues/account-management Diagnose and resolve the most common issues customers experience when managing their Pulsedive account. If you need to troubleshoot your Pulsedive account, explore these solutions to common issues. If you don't find your issue here, reach out to [Support](/support). ## How do I create an account? Registration happens in two parts: submit your email address, then complete your profile from the link Pulsedive sends you. 1. Go to [pulsedive.com](https://pulsedive.com/) and select **Sign Up**. 2. Enter the email address you want to use with Pulsedive, check the box to accept the Terms of Service and Privacy Policy, then select **Register**. 3. Find the email from `support@pulsedive.com` and select the link it contains to complete your profile. 4. Choose a username and password, then check the box to accept the Terms of Service and Privacy Policy again. 5. Select **Register**. Pulsedive confirms that registration is complete and redirects you to sign in. ## How do I delete my account? Deleting your account removes your account information from Pulsedive's database (in accordance with our [Privacy Policy](https://pulsedive.com/privacy)) and cancels any active subscriptions. Pulsedive retains your username even after deletion, so it can't be reused for a new account. > [!WARNING] > > Account deletion is permanent and can't be reversed. To delete your Pulsedive account: 1. [Go to your Account page](https://pulsedive.com/account). 2. From the navigation menu, select **Delete Account**. 3. Select the **Delete Account** button. 4. Check the box confirming that you understand what happens to your data when you delete your account, then select **Delete**. Your account is gone. Past comments stay visible, but your username no longer appears on them. ## How do I enable MFA? Multi-factor Authentication (MFA) adds a second authentication step to your login, so your account stays protected even if your password is compromised. 1. [Go to your Account page](https://pulsedive.com/account). 2. Select **Enable multi-factor authentication**. 3. Enter your password, and select **Continue**. 4. Scan the QR code with an authenticator app using your mobile device's camera. Alternatively, you can enter a setup key into your authenticator app. 5. In the next field, enter the code displayed for Pulsedive in your authenticator app. 6. Select **Verify Device**. 7. Copy your backup code and store it somewhere safe. You will need it if you lose your device or lose access to your authenticator app. 8. Check the box confirming that you have stored the code safely. 9. Select **Complete MFA Setup**. Pulsedive redirects you to your Account page, where `Enabled` now appears in the MFA section, and sends you an email notification. ## How do I turn off MFA? Turning off MFA removes the second authentication step from your login. 1. [Go to your Account page](https://pulsedive.com/account). 2. Select **Disable multi-factor authentication**. 3. Enter your password, check the box confirming you understand, then select **Disable**. Pulsedive redirects you to your Account page, where `Not enabled` now appears in the MFA section, and sends you an email notification. > [!NOTE] > > Disabling MFA invalidates your existing tokens and backup code, so if you re-enable it later, you will need to set up a completely new configuration. > [!WARNING] > > If you have lost access to your MFA device and can't log in to disable it yourself, please contact [support@pulsedive.com](mailto:support@pulsedive.com) immediately. ## Why am I not getting a notification email? Missing notification emails almost always come down to filtering or a typo at signup. Check these first: * **Spam or junk folder**: Notification emails sometimes get filtered. * **The email address you entered**: A typo at registration means the email never reaches you. If you need to change it, update it from your Account page, which sends a new notification email to the corrected address. ## How do I update my payment information? If you already have an active or past subscription, you can manage your payment information through your Account page. 1. [Go to your Account page](https://pulsedive.com/account). 2. From the navigation menu, select **Subscriptions**. 3. Select **Manage subscriptions**. Pulsedive redirects you to the Stripe-hosted billing portal, where you can update your payment method, billing email, cancel a subscription, or view past invoices. > [!WARNING] > > Remember to confirm your payment details before leaving the page, or your changes won't save. ## How do I download my data? Pulsedive keeps records of your account, submissions, and activity, and you can download any of them for your own records. 1. [Go to your Account page](https://pulsedive.com/account). 2. From the navigation menu, select **Your Data**. 3. Locate the category of data you would like to download, and select **Download**. Categories include: | Category | Description | | - | - | | Personal Data | Your account and personal details. | | Indicator Submissions | Indicators you have submitted as a web user or via the API, reflecting their current risk and properties. | | Raw Submission Data | Your raw submission records sent as a web user or via the API. | | Web Logs | Pages you have visited on the Pulsedive website, limited to the last six months. | | API Logs | Requests made with your API key, limited to the last six months. | ## Can I download all of my data at once? No. Because the data in each category comes from a different part of Pulsedive's system, each category downloads independently. If you need all five, please download each individually. # API Source: https://docs.pulsedive.com/troubleshoot/common-issues/api Diagnose and resolve the most common issues developers hit when working with Pulsedive's API. If you need to troubleshoot Pulsedive's API, explore these solutions to common issues. If you don't find your issue here, check the [API Reference](/api) or reach out to [Support](/support). ## How do I check my usage and limits? Check two places: * **Your account page**: Visit [pulsedive.com/account](https://pulsedive.com/account) to see your plan's limits and the **Activity** section for recent usage. * **Response headers**: Every API response includes headers showing your remaining requests for the current second, day, and month. ```text theme={null} X-Requests-Remaining-Second: 1 X-Requests-Remaining-Day: 9 X-Requests-Remaining-Month: 249 ``` Your rate limits depend on your plan, so these headers change based on what you are subscribed to. A missing header means there is no limit for that time period, and headers don't always appear on `429` error responses, which is why your account page is the more reliable source when a failed request doesn't show them. ## Why am I getting a 429 error? A `429` means you exceeded your plan's rate limit. Free, Pro, and standard Commercial plans enforce these limits directly, so exceeding one blocks the request. Higher Commercial tiers use soft limits instead, which don't block requests but may prompt Pulsedive to reach out if you consistently exceed them. **1. Check which limit you hit** Compare the request timing against the `X-Requests-Remaining-Second`, `-Day`, and `-Month` headers from your last successful request to identify whether you hit a per-second, per-day, or per-month cap. **2. Slow down or upgrade** Add delays between requests to stay under your per-second limit, or upgrade your [API plan](https://pulsedive.com/about/api) for higher limits. ## Why am I getting a 401 error? A `401` means Pulsedive didn't recognize the key on your request, and it is almost always caused by issues with an API key rather than a problem with your account itself. Check these three things, in order: * **Missing key**: Requests without a key work, but with much stricter limits. Add `&key=` to confirm this isn't the cause. * **Invalid key**: Double check the key against the one shown on your [account page](https://pulsedive.com/account). Keys aren't interchangeable between accounts. * **Key not authorized for the request**: Some data (like TAXII collections) requires a specific plan. Confirm your plan supports the endpoint you are calling. > [!NOTE] > > Your API key doesn't expire on its own. > If a previously working key stops authenticating, [contact Support](mailto:support@pulsedive.com) rather than generating a new one, since your existing key stays tied to your integrations. ## What do Pulsedive's API error codes mean? Every Pulsedive API endpoint returns errors in the same shape: ```json title="Example error response" theme={null} { "error": "Indicator not found." } ``` | Code | What to do | Why it happens | | - | - | - | | `400` | Check the `error` message for specifics, and review the parameter against the [API Reference](/api/overview). | Your request was malformed, or a parameter's value isn't valid (for example, an invalid Explore query or filter). | | `401` | See [Why am I getting a 401 error?](#why-am-i-getting-a-401-error) above. | Your API key is missing or invalid. | | `404` | Confirm the ID or value you're querying is correct. | The resource you requested (indicator, threat, feed, etc.) doesn't exist. | | `429` | Refer to the [Why am I getting a 429 error?](#why-am-i-getting-a-429-error) section. | You exceeded your plan's rate limit. | | `500` | Retry the request, and contact Support if it persists. | An unexpected error occurred on Pulsedive's end. These are automatically reported to the Pulsedive team. | # Browser Add-On Source: https://docs.pulsedive.com/troubleshoot/common-issues/browser-addon Resolve issues with highlighting, popups, and auto-scan behavior in the Pulsedive browser add-on. If you need to troubleshoot Pulsedive's browser add-ons, explore these solutions to common issues. If you don't find your issue here, check the [Add-on documentation](/addon/overview) or reach out to [Support](/support). ## Why isn't highlighting working on a page? Highlighting depends on how much of your selection is a valid indicator and whether the site's auto-popup is muted, so when nothing happens, work through these checks in order to find which cause applies: **1. Check what you highlighted** For a single indicator, the indicator needs to make up most of the highlighted text. This limits accidental triggers. For multiple indicators, the auto-popup only appears automatically if Bulk Parsing is enabled. **2. Try the add-on button directly** Select the add-on button in your browser toolbar after highlighting. It enriches the highlighted text regardless of auto-popup restrictions, so it works even in cases where the auto-popup wouldn't trigger. **3. Check for a mute exception** If nothing happens even with the button, check whether the site is muted. Select the add-on button, then check the **Unmute** menu, or review site exceptions in the add-on settings page. ## How do I turn auto-scan on or off? Use the auto-popup setting in the add-on. These options control how much it triggers: * **Mute for 5 minutes**: Pauses the auto-popup temporarily, then restores it automatically. * **Mute for this site**: Disables the auto-popup on the current domain until you remove the exception. * **Disable the auto-popup**: Turns auto-pop off across all sites. To undo, select the add-on button, then choose **Unmute**. The auto-popup is separate from the add-on button, so muting or disabling it doesn't turn off the add-on entirely. You can still highlight text and use the button for on-demand enrichment even with auto-popup fully disabled. # Feed Source: https://docs.pulsedive.com/troubleshoot/common-issues/feed Diagnose TAXII connectivity issues and errors when pulling a specific collection. If you need to troubleshoot Pulsedive's TAXII server, explore these solutions to common issues. If you don't find your issue here, check the [TAXII documentation](/taxii/overview) or reach out to [Support](/support). ## Why can't I connect to Pulsedive's TAXII server? An API key is required for every TAXII request, including the free test collection, so a connection failure is almost always a credentials or plan mismatch rather than a server-side issue. **1. Confirm your plan covers what you are connecting to** The test collection only needs a free API key. Connecting to the indicator or threat collections needs a Pro plan or any level of Feed plan. If you need to export the full dataset rather than just connect and query, that requires a Standard or Complete Feed plan specifically. **2. Confirm your credentials** Username is always `taxii2`. Password is your Pulsedive API key, which you can find on your account page. **3. Match your authentication method to your client** Most TAXII clients expect HTTP Basic Authorization: base64-encode `taxii2:` into the `Authorization` header. If your client lets you enter username and password separately, use `taxii2` and your API key directly, it will encode this for you. Query string authentication (`?key=`) works too, but it is meant for testing and debugging, not production clients. **4. Test against the discovery endpoint** Send a request to `https://pulsedive.com/taxii2/` with your chosen auth method. Both Basic Auth and query string authentication should return the same response. ## Why am I getting an error when I try to pull a collection? Collection errors usually trace back to a wrong ID or a plan mismatch, so start by confirming that you are using one of Pulsedive's three collection IDs: | Collection | ID | Access level | | - | - | - | | Test data | `981c4916-ebb2-4567-aece-54ae970c4230` | Free with API key | | Indicator data | `a5cffbfe-c0ff-4842-a235-cb3a7a040a37` | Pro or any Feed plan | | Threat data | `dc9ecfa5-7769-4cf3-b699-38a9776b431d` | Pro or any Feed plan | If the ID is correct, check what the error code is telling you: * `400`: A filter parameter is malformed, most often a `match[]` value that doesn't match the expected format, or a bad timestamp in `added_after`. * `401`: Your plan doesn't cover the collection you're requesting, or your credentials are wrong. Refer to the [Why can't I connect to Pulsedive's TAXII server?](#why-cant-i-connect-to-pulsedives-taxii-server) section. * `404`: The collection ID itself is wrong. Collection IDs are fixed; double check it against the table above rather than a value from another TAXII source. These collection IDs are hardcoded and won't change, so once a client is configured correctly, connectivity issues tend to come from plan or credential changes on your account rather than anything shifting on Pulsedive's end. # Risk Score Source: https://docs.pulsedive.com/troubleshoot/common-issues/risk-score Understand what's behind an indicator's risk score, and what to do if you disagree with it. If you need to troubleshoot risk scoring, explore these solutions to common issues. If you don't find your issue here, check the [Data Model documentation](/model/risk) or reach out to [Support](/support). ## How do I see why an indicator got its risk score? Look at the `riskfactors` array in the indicator's response. Each entry includes: * `description`: Human-readable explanation of the specific factor. * `risk`: Risk level that factor contributes. Pulsedive calculates risk automatically from observed data, and `riskfactors` is how that calculation gets surfaced back to you in plain language, rather than leaving you to infer it from raw properties alone. ## How do I check the underlying data behind a risk score? Cross-reference the `riskfactors` descriptions against the indicator's `attributes` and `properties` objects (WHOIS, HTTP, SSL, DNS, and so on). The risk factors reference the same observed data these objects contain, so you can trace a specific factor back to the specific evidence that produced it. > [!NOTE] > > `properties.http`, `properties.ssl`, `properties.meta`, and similar fields are only populated after an active scan (`probe=1`). > If a risk factor references data type you don't see in the response, the indicator likely hasn't had an active scan yet. ## How do I report a false positive? If you use Pulsedive Community, contact [Support](/support) and include any documentation that supports your case. Otherwise, you can override the risk manually using one of these methods: * Through feed configuration, if the indicator came from a feed * Through bulk management in Explore * By editing the indicator directly * Through individual or bulk submission via Analyze A manual override sets `manualrisk` to `1` and replaces the active `risk` value, while `risk_recommended` keeps showing Pulsedive's original automated assessment. That means overriding a false positive doesn't erase the system's reasoning, it just lets your judgment take precedence for that indicator going forward. > [!WARNING] > > Overriding risk changes what your exports and Explore queries return. > Both filter on the active `risk` value, so lowering an indicator from `critical` to `low` removes it from any `critical` pull, and nothing in the export records that it dropped out. > If a downstream tool blocks or alerts on your exports, remove the indicator there as well. > To learn more, refer to [Understand how filtering affects your dataset](/export/automate#understand-how-filtering-affects-your-dataset). # Scan Source: https://docs.pulsedive.com/troubleshoot/common-issues/scan Diagnose issues when a scan doesn't return the data you expect or seems stuck. If you need to troubleshoot scanning, explore these solutions to common issues. If you don't find your issue here, check the [Scan API documentation](/api/scan/overview) or reach out to [Support](/support). ## Why isn't my scan returning any information? Check which scan type you ran: * **Passive scan** (`probe=0`, the default): Collects WHOIS, DNS, and other metadata that doesn't require contacting the indicator directly. * **Active scan** (`probe=1`): Additionally collects HTTP headers, SSL/TLS certificate details, page metadata, cookies, service banners, and a DOM screenshot. If you are expecting HTTP, SSL, or metadata properties and only ran a passive scan, rerun with `probe=1` to get that data. Passive scans don't contact the indicator at all, so they can't return data that only an active scan collects. This is deliberate: passive scanning stays quiet, while active scanning is more thorough but generates traffic to the indicator itself (like lightweight port scans and browser requests). > [!TIP] > > If you want the scan saved and searchable later, add `submit=1` to your request. > Without it, Pulsedive enriches and scores the indicator but doesn't store it. ## Why is my scan stuck or taking a long time? Active scans take longer than passive scans because they wait on real network responses, such as page loads, certificate handshakes, and port checks, rather than metadata lookups. A scan that is still in progress isn't necessarily stuck, though maintenance or downtime on Pulsedive can also hold one up. **1. Confirm you're polling with the right queue ID** Use the `qid` returned from your original `POST` request to `/api/analyze.php`, not the indicator's `iid`. **2. Check the status and stage fields** Poll `GET /api/analyze.php?qid=`. While the scan runs, the response includes a `status` and a `stage` field showing what step it is on. A `data` object only appears once scanning completes. **3. Poll at a reasonable interval** Poll roughly every 500 ms. Polling doesn't count against your rate limit, so there's no cost to checking frequently within that guideline. **4. Check for maintenance** If the scan is still running after five minutes, check [pulsedive.com](https://pulsedive.com) for a maintenance notice. Ongoing maintenance or downtime can stall scans. **5. Start a new scan** If there is no maintenance notice and the scan still hasn't finished after five minutes, start a new scan. If `status` never changes after a few minutes of polling, [contact Support](/support) with your `qid`. # Connecting to the Pulsedive Docs MCP server Source: https://docs.pulsedive.com/troubleshoot/resources/docs-mcp Connect Claude, Cursor, and other AI tools to a read-only MCP server so they can search Pulsedive's documentation directly. Pulsedive publishes a read-only MCP (Model Context Protocol) server for this documentation site. When you connect an AI tool to it, the tool can search and retrieve current Pulsedive documentation while it answers your questions, instead of relying on training data that might be outdated or incomplete. Connecting doesn't require a Pulsedive account or API key. ## Quick Setup If you're already familiar with setting up connectors in your AI tool, use this URL for the Pulsedive Docs MCP server: ```text theme={null} https://docs.pulsedive.com/mcp ``` Our docs don't require authentication, so you won't be prompted to log in. ## Connect Your AI Tool Setup steps differ by tool, but the pattern is the same throughout: point the tool at the server URL above, and skip any authentication step since none is required. **Claude** **1. Add a custom connector** 1. Go to the [Connectors](https://claude.ai/settings/connectors) page in your Claude settings. 2. Click **Add custom connector**. 3. Enter a name, such as `Pulsedive Docs`, and paste in the server URL. 4. Click **Add**. **2. Enable the connector for a chat** Click the attachments button (the plus icon) next to the message box, then select the Pulsedive Docs connector. Claude can now search these docs while it responds. **Claude Code** **1. Add a custom connector** Run the following command: ```bash theme={null} claude mcp add --transport http pulsedive-docs https://docs.pulsedive.com/mcp ``` **2. Verify the connection** Run the following command: ```bash theme={null} claude mcp list ``` The output should include `pulsedive-docs` with a connected status. **Codex CLI** **1. Add the server** Add the following to `~/.codex/config.toml`. Create the file if it doesn't already exist. ```toml theme={null} [mcp_servers.pulsedive-docs] url = "https://docs.pulsedive.com/mcp" ``` **2. Verify the connection** 1. Restart your Codex session for the change to take effect. 2. Confirm the connection by asking Codex which MCP servers it has access to. The response should include `pulsedive-docs`. **Cursor** **1. Open MCP settings** 1. Open the command palette with Command + Shift + P (Mac) or Ctrl + Shift + P (Windows). 2. Search for **Open MCP settings**. 3. Select **Add custom MCP**. The `mcp.json` file opens. **2. Add the server** Add the following entry: ```json theme={null} { "mcpServers": { "pulsedive-docs": { "url": "https://docs.pulsedive.com/mcp" } } } ``` **VS Code** **1. Create a config file** Create a `.vscode/mcp.json` file in your project. **2. Add the server** Add the following entry: ```json theme={null} { "servers": { "pulsedive-docs": { "type": "http", "url": "https://docs.pulsedive.com/mcp" } } } ``` **ChatGPT** > [!NOTE] > > Custom connectors need a paid ChatGPT plan and Developer Mode turned on. > On Business and Enterprise workspaces, an admin may need to enable custom connectors first. **1. Turn on Developer Mode** 1. Go to **Settings** > **Apps & Connectors** > **Advanced settings**. 2. Switch on **Developer mode**. **2. Add a custom connector** 1. Go to **Settings** > **Connectors**. 2. Select **Create**. 3. Enter a name, such as `Pulsedive Docs`, and paste in the server URL (`https://docs.pulsedive.com/mcp`). 4. Set authentication to **No auth**. 5. Save the connector. **3. Use it in a chat** 1. Click the **+** icon next to the message box. 2. Select the Pulsedive Docs connector and enable it for the conversation. **Gemini CLI** **1. Add a custom connector** Run the following command: ```bash theme={null} gemini mcp add --transport http pulsedive-docs https://docs.pulsedive.com/mcp ``` Alternatively, add the server directly to your `~/.gemini/settings.json` (or a project-level `.gemini/settings.json`): ```json theme={null} { "mcpServers": { "pulsedive-docs": { "httpUrl": "https://docs.pulsedive.com/mcp" } } } ``` **2. Verify the connection** 1. Restart the Gemini CLI. 2. Run `/mcp` to confirm `pulsedive-docs` shows as connected. ## Using the Connection Once you're connected, ask questions about Pulsedive as you normally would, and your AI tool will decide on its own when to search these docs for an answer instead of relying on what it already knows.