# Create asset Source: https://docs.defendis.com/api-reference/assets-watchlist/create-asset /openapi.json post /api/v1/watchlists/assets # Delete assets Source: https://docs.defendis.com/api-reference/assets-watchlist/delete-assets /openapi.json post /api/v1/watchlists/assets/delete # List assets Source: https://docs.defendis.com/api-reference/assets-watchlist/list-assets /openapi.json get /api/v1/watchlists/assets # Update asset Source: https://docs.defendis.com/api-reference/assets-watchlist/update-asset /openapi.json put /api/v1/watchlists/assets/{id} # Create BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/create-bin /openapi.json post /api/v1/watchlists/bin Creates a BIN in the current enterprise watchlist. # Delete BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/delete-bins /openapi.json post /api/v1/watchlists/bin/delete # List BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/list-bins /openapi.json get /api/v1/watchlists/bin # Update BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/update-bin /openapi.json put /api/v1/watchlists/bin/{id} # Credentials (domain) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-domain /openapi.json get /api/v1/dataleaks/credentials # Credentials (email) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-email /openapi.json get /api/v1/dataleaks/credentials/email # Dataleaks stats Source: https://docs.defendis.com/api-reference/dataleaks/dataleaks-stats /openapi.json get /api/v1/dataleaks/stats # Documents (domain) Source: https://docs.defendis.com/api-reference/dataleaks/documents-domain /openapi.json get /api/v1/dataleaks/documents # Payment Cards Source: https://docs.defendis.com/api-reference/dataleaks/payment-cards /openapi.json get /api/v1/dataleaks/paymentcards/bins # Victim profile Source: https://docs.defendis.com/api-reference/dataleaks/victim-profile /openapi.json get /api/v1/dataleaks/user # Create domain Source: https://docs.defendis.com/api-reference/domains-watchlist/create-domain /openapi.json post /api/v1/watchlists/domain Creates a domain in the current enterprise watchlist. # Delete domains Source: https://docs.defendis.com/api-reference/domains-watchlist/delete-domains /openapi.json post /api/v1/watchlists/domain/delete # List domains Source: https://docs.defendis.com/api-reference/domains-watchlist/list-domains /openapi.json get /api/v1/watchlists/domain # Update domain Source: https://docs.defendis.com/api-reference/domains-watchlist/update-domain /openapi.json put /api/v1/watchlists/domain/{id} # Create executive Source: https://docs.defendis.com/api-reference/executives-watchlist/create-executive /openapi.json post /api/v1/watchlists/executive # Delete executives Source: https://docs.defendis.com/api-reference/executives-watchlist/delete-executives /openapi.json post /api/v1/watchlists/executive/delete # List executives Source: https://docs.defendis.com/api-reference/executives-watchlist/list-executives /openapi.json get /api/v1/watchlists/executive # Update executive Source: https://docs.defendis.com/api-reference/executives-watchlist/update-executive /openapi.json put /api/v1/watchlists/executive/{id} # CVE details Source: https://docs.defendis.com/api-reference/exposure/cve-details /openapi.json get /api/v1/exposure/cves/{id} # CVEs Source: https://docs.defendis.com/api-reference/exposure/cves /openapi.json get /api/v1/exposure/cves # DNS records Source: https://docs.defendis.com/api-reference/exposure/dns-records /openapi.json get /api/v1/exposure/dns # Hosts Source: https://docs.defendis.com/api-reference/exposure/hosts /openapi.json get /api/v1/exposure/hosts # JavaScript findings Source: https://docs.defendis.com/api-reference/exposure/javascript-findings /openapi.json get /api/v1/exposure/js # Ports Source: https://docs.defendis.com/api-reference/exposure/ports /openapi.json get /api/v1/exposure/ports # Subdomains Source: https://docs.defendis.com/api-reference/exposure/subdomains /openapi.json get /api/v1/exposure/subdomains # Surface vulnerabilities Source: https://docs.defendis.com/api-reference/exposure/surface-vulnerabilities /openapi.json get /api/v1/exposure/vulnerabilities # Health Source: https://docs.defendis.com/api-reference/health/health /openapi.json get /health # Create keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/create-keyword /openapi.json post /api/v1/watchlists/keyword Creates a keyword in the current enterprise watchlist. # Delete keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/delete-keywords /openapi.json post /api/v1/watchlists/keyword/delete # List keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/list-keywords /openapi.json get /api/v1/watchlists/keyword # Update keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/update-keyword /openapi.json put /api/v1/watchlists/keyword/{id} # Create ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/create-ransom-group /openapi.json post /api/v1/watchlists/ransom # Delete ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/delete-ransom-groups /openapi.json post /api/v1/watchlists/ransom/delete # List ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/list-ransom-groups /openapi.json get /api/v1/watchlists/ransom # Update ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/update-ransom-group /openapi.json put /api/v1/watchlists/ransom/{id} # Group details Source: https://docs.defendis.com/api-reference/ransomware/group-details /openapi.json get /api/v1/ransom/groups/{id} # Groups Source: https://docs.defendis.com/api-reference/ransomware/groups /openapi.json get /api/v1/ransom/groups # Ransomware stats Source: https://docs.defendis.com/api-reference/ransomware/ransomware-stats /openapi.json post /api/v1/ransom/stats # Victims Source: https://docs.defendis.com/api-reference/ransomware/victims /openapi.json get /api/v1/ransom/victims # Victims (by country) Source: https://docs.defendis.com/api-reference/ransomware/victims-by-country /openapi.json get /api/v1/ransom/country/victims # Create group Source: https://docs.defendis.com/api-reference/watchlists/create-group /openapi.json post /api/v1/watchlists/create # Delete groups Source: https://docs.defendis.com/api-reference/watchlists/delete-groups /openapi.json post /api/v1/watchlists/delete # Group stats Source: https://docs.defendis.com/api-reference/watchlists/group-stats /openapi.json get /api/v1/watchlists/stats # List groups Source: https://docs.defendis.com/api-reference/watchlists/list-groups /openapi.json get /api/v1/watchlists # Update group Source: https://docs.defendis.com/api-reference/watchlists/update-group /openapi.json put /api/v1/watchlists/{id} # Authentication Source: https://docs.defendis.com/api/auth Defendis API uses bearer API keys for authentication and enterprise scope for authorization. ## API key Send your API key in the `Authorization` header for all customer endpoints under `/api/v1/*`: ```http theme={null} Authorization: Bearer ``` ```bash theme={null} #Example request: curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## API key lifecycle API keys are created and managed in [Defendis web app](https://app.defendis.com). Use unique keys per integration (SIEM, data lake ingestion, SOAR automation). Rotate keys on a schedule (every 60 to 90 days) and immediately after any suspected exposure. Revoke unused keys promptly to reduce your exposure. ## Authorisation scope Each API key is bound to a workspace scope. The API enforces access to workspace-owned resources and input validation for scoped endpoints. Out-of-scope requests will return 403 Forbidden Dataleaks endpoints are intentionally strict to prevent data leakage: * Requests require scoped inputs (`domain`, `email`, or `bin` depending on endpoint). * Missing required scoped parameters return 400 Bad Request. * Out-of-scope inputs return 403 Forbidden.. * Enterprise billing access restrictions may also return 403 Forbidden on protected routes. ## Common failures ```http theme={null} # Missing API key HTTP/1.1 401 Unauthorized { "error": "Missing API key" } ``` ```http theme={null} # Invalid or revoked API key HTTP/1.1 401 Unauthorized { "error": "Invalid or revoked API key" } ``` ## Securing your integration These recommendations cover the minimum security and observability controls we expect for production integrations, including secrets handling, least-privilege access, and request correlation: Store API keys in a secret manager, never in source control or client-side code. Restrict key access to only the workloads that need it. Never log the full Authorization header. Capture `x-request-id` response header to speed up investigations. # Deployment Source: https://docs.defendis.com/api/deployment This page explains how the Defendis API evolves over time: versioning guarantees, compatibility expectations, and the practices you should follow to keep production integrations stable. ## Versioning policy Defendis uses path-based versioning. Current customer API is `/api/v1` ### Backward-compatible changes We may introduce backward-compatible improvements without changing the version, including: Adding new endpoints. Adding new optional query parameters. Adding new fields to existing responses. For forward compatibility, ignore unknown response fields and avoid strict JSON parsing that fails on additional properties. ### Breaking changes Breaking changes will be introduced under a new version prefix `/api/v2`. # endpoints Source: https://docs.defendis.com/api/endpoints This page gives you a practical map of which endpoint families exist, what they’re used for, and how they fit together in a real integration. ## Recommended integration flow Most customer integrations follow this pattern: Use watchlists to define scope (domains, keywords, BINs, executives, assets). Query Dataleaks, Exposure, and Ransomware datasets with scoped inputs. Ingest incrementally using pagination and date windows where supported. Normalize and correlate results into downstream systems such as SIEM, SOAR, a data lake, or case management. ## Response envelope Successful responses use a consistent top-level envelope: ```json title="Single resource" theme={null} { "data": { "...": "..." } } ``` ```json title="List endpoints" theme={null} { "data": [{ "...": "..." }], "paging": { "...": "..." } } ``` ```json title="Batch delete" theme={null} { "data": { "count": 3 } } ``` ## Health Use this for basic connectivity checks (no auth required): ```bash title="Health request" theme={null} curl -sS "https://api.defendis.com/health" ``` ## Watchlists Watchlists are the foundation of authorization scope. * `GET /api/v1/watchlists` * `POST /api/v1/watchlists/create` * `PUT /api/v1/watchlists/{id}` * `POST /api/v1/watchlists/delete` * `GET /api/v1/watchlists/stats` * `GET /api/v1/watchlists/assets` * `POST /api/v1/watchlists/assets` * `PUT /api/v1/watchlists/assets/{id}` * `POST /api/v1/watchlists/assets/delete` * `GET /api/v1/watchlists/domain` * `POST /api/v1/watchlists/domain` * `PUT /api/v1/watchlists/domain/{id}` * `POST /api/v1/watchlists/domain/delete` * `GET /api/v1/watchlists/bin` * `POST /api/v1/watchlists/bin` * `PUT /api/v1/watchlists/bin/{id}` * `POST /api/v1/watchlists/bin/delete` * `GET /api/v1/watchlists/executive` * `POST /api/v1/watchlists/executive` * `PUT /api/v1/watchlists/executive/{id}` * `POST /api/v1/watchlists/executive/delete` * `GET /api/v1/watchlists/keyword` * `POST /api/v1/watchlists/keyword` * `PUT /api/v1/watchlists/keyword/{id}` * `POST /api/v1/watchlists/keyword/delete` * `GET /api/v1/watchlists/ransom` * `POST /api/v1/watchlists/ransom` * `PUT /api/v1/watchlists/ransom/{id}` * `POST /api/v1/watchlists/ransom/delete` Many list endpoints accept an optional `watchlistid` query parameter, and batch-delete endpoints use a JSON request body with an `ids` array. `POST /api/v1/watchlists/domain`, `POST /api/v1/watchlists/keyword`, and `POST /api/v1/watchlists/bin` can return: * `403 Forbidden` when enterprise billing access is denied. * `409 Conflict` when the corresponding workspace quota is reached (`quota_domains_reached`, `quota_keywords_reached`, `quota_bins_reached`). ## Modules * `GET /api/v1/dataleaks/credentials` // requires `domain` * `GET /api/v1/dataleaks/credentials/email` // requires `email` * `GET /api/v1/dataleaks/documents` // requires `domain` * `GET /api/v1/dataleaks/paymentcards/bins` // requires `bin` * `GET /api/v1/dataleaks/stats` // requires `domain` * `GET /api/v1/dataleaks/user` // requires `id` * `GET /api/v1/exposure/cves` * `GET /api/v1/exposure/subdomains` * `GET /api/v1/exposure/hosts` // requires `domainId` * `GET /api/v1/exposure/ports` * `GET /api/v1/exposure/vulnerabilities` Start with `subdomains` and `hosts` to build inventory, then use `ports` and `vulnerabilities` for risk triage and reporting. * `POST /api/v1/ransom/stats` // overview stats and trends * `GET /api/v1/ransom/groups` // actor and group listing * `GET /api/v1/ransom/groups/{id}` // group details * `GET /api/v1/ransom/victims` // victim activity listing * `GET /api/v1/ransom/country/victims` // victim activity by country # Errors Source: https://docs.defendis.com/api/errors Defendis API uses standard HTTP status codes and a JSON error envelope. This page explains how to handle errors safely in production, including which scenarios are retryable. ## Error response format Most error responses use this shape: ```json theme={null} { "error": "string", "message": "string (optional)" } ``` Implementation principles: Treat error as a human-readable reason, not a stable enum. Ignore unknown response fields for forward compatibility. Never log secrets, especially the `Authorization` header. ## Status codes and retry actions | Status code | Meaning | Retry strategy | Recommended action | | ----------------------- | ----------------------------------------------------- | -------------- | ---------------------------------------------------------------- | | `400 Bad Request` | Missing or invalid parameters/JSON body | No | Fix request shape or required inputs | | `401 Unauthorized` | Missing, invalid, or revoked API key | No | Validate credentials and replace/re-enable key | | `403 Forbidden` | Authenticated but blocked by enterprise access policy | No | Verify enterprise scope/eligibility and enterprise billing state | | `409 Conflict` | Workspace quota reached on write operations | No | Reduce usage or increase workspace quotas, then retry | | `404 Not Found` | Unknown endpoint or resource | No | Confirm endpoint path, method, and resource identifiers | | `429 Too Many Requests` | Rate limit exceeded | Yes | Retry with exponential backoff + jitter | | `500/502/503/504` | Transient server-side failure | Conditional | Retry safe requests (`GET`) with backoff | ## Common examples | Scenario | HTTP status | Example error body | | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | Missing API key | `401 Unauthorized` | `{ "error": "Missing API key" }` | | Out-of-scope request | `403 Forbidden` | `{ "error": "You don't have permission to view this" }` | | Enterprise billing access denied | `403 Forbidden` | `{ "error": "Enterprise billing access denied", "reason": "payment_unpaid", "status": "unpaid" }` | | Watchlist quota reached | `409 Conflict` | `{ "error": "quota_domains_reached", "metric": "domains", "used": 10, "limit": 10, "requestedIncrement": 1 }` | | Rate limit exceeded | `429 Too Many Requests` | `{ "error": "Rate limit exceeded" }` | ### Backoff snippet ```js title="JavaScript backoff snippet" theme={null} function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); } async function fetchGetWithBackoff(url, options = {}, { maxRetries = 5, baseDelayMs = 500 } = {}) { const retryableStatuses = new Set([429, 500, 502, 503, 504]); for (let attempt = 0; attempt <= maxRetries; attempt++) { try { const res = await fetch(url, { ...options, method: "GET" }); if (!retryableStatuses.has(res.status)) return res; if (attempt === maxRetries) return res; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } catch (error) { if (attempt === maxRetries) throw error; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } } } ``` ```python title="Python backoff snippet" theme={null} import random import time import requests def get_with_backoff(url, headers, max_retries=5, base_delay_s=0.5, timeout_s=30): retryable_statuses = {429, 500, 502, 503, 504} for attempt in range(max_retries + 1): try: resp = requests.get(url, headers=headers, timeout=timeout_s) except requests.RequestException: if attempt == max_retries: raise resp = None if resp is not None and resp.status_code not in retryable_statuses: return resp if attempt == max_retries: return resp delay = min(30.0, base_delay_s * (2 ** attempt)) jitter = random.uniform(0, 0.25) time.sleep(delay + jitter) ``` ## Troubleshooting checklist When contacting Support, include: Include the request path `example: /api/v1/dataleaks/stats` Include the UTC timestamp and your client request ID. Include the HTTP status code and the error response body. Include the parameters you sent, with sensitive values redacted. # Getting Started Source: https://docs.defendis.com/api/getting-started This guide helps you make your first successful request to the Defendis API and adopt conventions that make your integration reliable in production. ## Quickstart ```http theme={null} curl -sS "https://api.defendis.com/health" ``` ```http theme={null} #Expected response: { "status": "ok" } ``` ```bash theme={null} export DEFENDIS_API_KEY="YOUR_API_KEY" ``` ```bash theme={null} curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## Core concepts ### Watchlists Datasets in Defendis are access-controlled by your workspace scope. In practice: * You define watchlists that represent what you are authorised to monitor (`domains`, `emails`, `keywords`, `BINs`, and other assets). * Many endpoints validate input against your watchlist scope. * Requests outside your approved scope return 403 Forbidden. * Watchlist write endpoints may return 409 Conflict when your workspace quota is reached. ### Contract-first integration * The OpenAPI spec is the source of truth for endpoints, parameters, and request/response schemas: `../openapi.yaml`. * If you generate clients, treat the API as additive: new fields may appear without warning. Your parser should ignore unknown fields. ## Request conventions ### Content types * Use query parameters for filtering and pagination on endpoints that support them. * When an endpoint accepts a request body, send JSON: ```http theme={null} Content-Type: application/json ``` For more information, see [Errors](/api/errors) and [Endpoints](/api/endpoints). ### Pagination Paginated list endpoints return a consistent envelope: * `data`: array of records * `paging`: pagination metadata with: * `currentPage` * `pageSize` * `totalRecords` * `totalPages` * `hasMore` * `nextPage` Recommended ingestion loop: * Start with `page=1`. * Keep fetching until `paging.hasMore` is `false` (or `paging.nextPage` is `null`). * Persist checkpoints (page and filter window) so your ingestion can resume safely after failures. ```json title="Example" theme={null} { "data": [], "paging": { "currentPage": 1, "pageSize": 50, "totalRecords": 120, "totalPages": 3, "hasMore": true, "nextPage": 2 } } ``` ### Date filters Some endpoints support date window filtering. When supported, use a closed-open window: * `fromDate`: inclusive lower bound * `toDate`: exclusive upper bound Date parameters are standardized as `fromDate` and `toDate`. Always follow the endpoint’s reference docs / OpenAPI contract for exact support. Client recommendation: * Use `YYYY-MM-DD` for date-only filters. * Prefer narrow windows for high-volume pulls and widen gradually. ### Search & sorting Search and sorting are endpoint-specific. Common patterns include: * `search` * `sortBy` * `sortOrder` When omitted, server-side defaults apply. Use the OpenAPI contract and the endpoint reference docs to confirm supported parameters and allowed values. ## Rate limits & reliability Defendis enforces rate limiting. When exceeded you will receive 429 Too Many Requests. Client best practices: * Use exponential backoff for retries (with jitter). * Distribute polling workloads over time. * Automatically retry **safe** requests (GET) on transient failures (`429`, `5xx`, timeouts). * Avoid retrying non-idempotent writes unless your application guarantees idempotency. ## Typical integration patterns ### Pull model Configure watchlists so your integration only pulls data within approved scope. Ingest Dataleaks, Exposure, and Ransomware datasets on a recurring schedule. Map results into your SIEM/SOAR, data lake, or case management schema. ### Near-real-time workflows For operational workflows, use frequent polling with small time windows and robust retry/backoff behavior. ## Data handling & privacy Some datasets, especially `Dataleaks`, may contain sensitive information. As an API consumer, you are responsible for ensuring the data is handled appropriately within your environment. Recommended practices: Keep only the fields and retention window required for your workflow. Limit sensitive dataset access to the smallest set of users and services. Avoid logging full payloads or sensitive fields in application and audit logs. Apply your internal security, legal, and compliance controls to this API data. # Introduction Source: https://docs.defendis.com/api/index Defendis API lets you integrate external threat signals into your product and security workflows to automate monitoring and enrichment. Use this API to: Query data leak signals for approved identifiers (domains, BINs, etc). Create and manage watchlists that define what you monitor. Analyse your external exposure and track ransomware activity. ## Base URL and versioning * Base URL: `https://api.defendis.com` * Version prefix: `/api/v1` Example endpoint: `https://api.defendis.com/api/v1/watchlists` ## Authentication All `/api/v1/*` endpoints require an API key: ```http theme={null} Authorization: Bearer ``` ## Start here Make your first request and learn integration patterns. API keys, authorization scope, and security best practices. Guidance on which endpoint family to use, with OpenAPI reference. Error model, retry behavior, and troubleshooting. Availability, versioning policy, and change management. ## Downloads * Download the `Postman file` * Import the OpenAPI spec URL: `https://api.defendis.com/openapi.json` # Changelog Source: https://docs.defendis.com/changelog ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Navigation and usability improvements and integration enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved API integration access and configuration flows ### Navigation and usability improvements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks ### Navigation and usability improvements and alerting enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved reliability of notifications and alerts ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Integration access and developer experience improvements and security enhancements * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding * More reliable behavior for enterprise integration scenarios * Strengthened account access and verification flows ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Service‑Provider Billing & Workspace Improvements * Introduced service‑provider‑managed billing for more flexible workspace payments * Enhanced billing breakdowns for clearer cost visibility * Improved signup and verification flow for a smoother onboarding experience * Fixed minor issues and refreshed documentation pages for better clarity ### Improved Billing * Enhanced billing management * General refinements for better reliability and maintainability ### Enhanced Billing, Security, and Workspace Controls * *Stronger account security:* Refined MFA and session handling to ensure smoother, more reliable authentication * Strengthened account access and verification flows ### Improved Access and reliability * Enhanced subscription permission checks for smoother access * Improved overall product stability and reliability ### Improved Trial License and Billing Display * Clearer display of billing amounts for all license types * Enhanced handling of trial licenses for a smoother experience * More accurate and transparent billing information throughout the app * Improved overall product stability and reliability ### Improved Reliability for Authentication Requests * Extended retry window for temporary authentication issues to reduce login interruptions * Enhances overall stability when network conditions are inconsistent * Provides a smoother sign-in experience with fewer transient errors * Improved overall product stability and reliability ### Improved Session Stability and Refresh Handling * Enhanced session handling ensures smoother reconnections and fewer interruptions * Provides a more reliable and consistent experience when working across multiple sessions * Strengthened account access and verification flows ### Improved Stability and Minor Enhancements * Enhanced overall app stability for a smoother experience * Fixed minor issues to improve reliability and performance * Optimized background processes for faster response times * Improved overall product stability and reliability ### Improved Billing, Authentication, and Subscription Experience * Smarter billing: Introduces catalog-based billing with flexible, document-level discounts * Smoother sign-in: Enhanced authentication retry flow and refined interface for better usability * Faster loading: Updated loading visuals and automatic fallback for terminal licenses ### Improved Billing and Access Experience * Enhanced billing workflows for greater accuracy and reliability * Streamlined access controls to ensure smoother user management * Minor performance and stability improvements across the platform * Improved API integration access and configuration flows ### Improved Deployment Security and Performance * Enhanced deployment process with secure Google Cloud integration * Improved reliability through updated service account management * Improved reliability of notifications and alerts * Better clarity when tracking important updates ### Improved Security, Streaming, and Workspace Controls * Enhanced session management with new logout options and smoother refresh handling * Strengthened workspace access controls with billing fallback for uninterrupted service * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced Member Notifications in Console * Introduces a new notifications feature for console members * Enables real-time updates and alerts directly within the console * Improves visibility and responsiveness for team activities * Delivers a smoother, more connected user experience ### Improved Billing, Permissions, and Workspace Management * Enhanced billing experience with new payment form states and improved Stripe integration * Added permission catalog service for more flexible access control * Improved workspace management with safer deletion and new catalog features * Improved API integration access and configuration flows ### Improved Workspace Experience * Introduced enhanced workspace management with clearer allocation and usage controls * Improved user and billing management capabilities for workspace administrators * Improved navigation and overall usability ### Improved Workspace Management and Onboarding * Introduced user verification and guided onboarding sessions for a smoother start * Enhanced invite acceptance and redirect flow for a more seamless joining experience * Improved session reliability and visual alignment in the header ### Improved Data Security and Billing Reliability * General stability and performance enhancements for smoother operations * Improved overall product stability and reliability * Enhanced usability across key product areas ### Improved Workspace Billing Sync * Reduces potential discrepancies in billing information * Provides a smoother experience when managing workspace billing changes * Improved navigation and overall usability ### Improved Search Efficiency and Workspace Access Alignment * Search updates are now faster and more responsive, reducing unnecessary refreshes * Overall experience is smoother with improved performance and reliability * Improved product responsiveness across key pages ### Improved Workspace Insights and Session Reliability * Enjoy smoother session experiences with enhanced refresh handling * Improved reliability and control for workspace management tasks * Improved API integration access and configuration flows ### Performance and Stability Improvements * Enhanced overall app responsiveness for a smoother experience * Improved reliability to reduce unexpected errors * Minor interface refinements for better usability * General maintenance updates to keep things running efficiently ### Workspace Stability Improvements * Improved handling of approved workspace differences to reduce unnecessary alerts * General stability and performance enhancements for smoother workspace operations * Improved navigation and overall usability ### Improved Enterprise Billing Accuracy and Data Access * Improved data retrieval for faster and more reliable billing information * Streamlined reconciliation process to reduce potential discrepancies * Improved overall product stability and reliability ### Improved Billing Options and License Sync * Added support for a **Free** billing status to simplify account management * Workspaces now automatically **synchronize license details**, ensuring accurate and up‑to‑date access * Enhancements improve transparency and reduce manual updates for workspace admins * Improved navigation and overall usability ### Improved Workspace Licensing and Error Handling * Introduced enhanced workspace licensing with updated data models * Improved reliability through better error handling and duplicate prevention * Streamlined membership updates to maintain consistency and accuracy * Refreshed documentation pages for clearer guidance ### Improved Reports * Generate reports with your enterprise avatar and default logo for a more personalized look * Analytics now automatically adapts to your region for more accurate insights * Improved export usability ### Improved reliability for notification counts * Notification counts now update more consistently, even in unstable network conditions * Enhanced error handling ensures smoother user experience when fetching notifications * Overall reliability and responsiveness of notifications have been improved ### Enhanced Authentication * Improved sign-in reliability with updated authentication flow * Provides a smoother and more secure reauthentication experience for users * Strengthened account access and verification flows ### Improved API and Watchlist Management * Added enterprise ID support to API calls for better integration and control * Enhanced watchlist domain management for more accurate tracking * Improved CVE asset matching to strengthen vulnerability insights * Improved API integration access and configuration flows ### Improved app stability, CVE Tools, and Ransomware Insights * Enhanced authentication, Improved performance, and clearer error feedback * Added ransomware victim summaries, detailed views, and country-based filtering for deeper insights * Strengthened account access and verification flows ### Improved Error Handling and Watchlist Enhancements * Enhanced watchlist functionality with enterprise-grade validation * Improved overall stability and consistency across the platform * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Improved performance and simplified app behavior * Streamlined app configuration for faster load times * Reduced unnecessary redirects to improve navigation * Enhanced reliability and consistency across user sessions * Improved navigation and overall usability ### Improved Authentication and Session Reliability * Added automatic redirection to help users recover sessions after cutover events * Enhanced session handling for smoother, more reliable sign-ins * Improved overall stability and continuity during authentication transitions * Strengthened account access and verification flows ### Improved Resource Management with Custom Cache Controls * Enhanced performance through smarter caching behavior * Faster load times and reduced redundant data requests * More consistent user experience when accessing stored resources * Improved navigation and overall usability ### Improved API performance and reliability * Enhanced API responsiveness with smarter rate limiting for task updates * Improved connection stability to ensure smoother, more consistent interactions * Delivers a faster and more reliable experience for high-volume API users * Improved API integration access and configuration flows ### Improved Task Status Tracking and Batch Updates * Enjoy more accurate and consistent task progress updates * Benefit from smoother monitoring of large-scale task operations * Improved API integration access and configuration flows ### Improved Enterprise Update Experience * Enhanced enterprise update process for smoother data management * General usability improvements for a faster, more reliable experience * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Improved Support Experience and Settings Enhancements * Introduced a new Support Overview for easier access to key support information * Enhanced Support Settings with clearer labels and a more intuitive layout * Streamlined navigation to help users manage support preferences more efficiently * Improved API integration access and configuration flows ### Improved Billing and watchlist management * Past due accounts are now subject to a 7 days grace period * More accurate scope validation and smoother loading states in your watchlist dropdown * Faster, more reliable interactions across tasks management * Improved API integration access and configuration flows ### Improved Chat User Identity and Settings * Enhanced Chat integration for more accurate user identification * Simplified configuration options for managing communication settings * Improved reliability and consistency in user messaging experiences * Strengthened account access and verification flows ### Improved Task Management and Session Handling * Enhanced task management experience with improved UI and selection tools * Improved session and authentication handling for more reliable logins and logouts ### Improved Dashboard Stability and Error Handling * Enhanced reliability of dashboard statistics display * Improved handling of unexpected data or connection issues * Reduced likelihood of dashboard errors impacting user experience * Improved reporting and export usability ### Improved Session Reliability and Fraud Detection * Enhanced session management for more reliable and secure user experiences * Updated billing documentation for clearer incident response guidance * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages ### Improved Fraud Detail Loading Performance * Faster loading times when viewing fraud details * Smoother experience when switching between fraud cases * Enhanced reliability and consistency in fraud data display * Improved product responsiveness across key pages ### Enhanced Fraud Management and Navigation * Updates fraud tabs and localization for a clearer, more consistent interface * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages * Better readability in user-facing content ### Improved Subscription Stability and Error Handling * Enhanced reliability when managing enterprise subscriptions * Reduced likelihood of subscription errors and interruptions * Improved clarity of error messages for smoother user experience * Improved overall product stability and reliability ### Improved Host Node Display in Surface Maps * Host node visuals now render with consistent width for better clarity * Enhanced readability and alignment across different map views * Minor stability improvements for smoother map interactions * Improved overall product stability and reliability ### Enhanced Feed, Intelligence, and Map Experiences * Introduced a new integrated feed experience with improved performance and real-time updates * Expanded intelligence features with enhanced loading states and new airport country insights * Refreshed map visuals and improved key management for smoother navigation * Added richer surface map details, including DNS summaries and clearer host information ### Easily Delete Workspaces * Added the ability to permanently delete workspaces when no longer needed * Simplifies workspace management and keeps your environment organized * Ensures a smoother experience when cleaning up unused projects * Improved navigation and overall usability ### Integration access and developer experience improvements * Improved API integration to support more reliable connections * Increased overall stability and performance for development operations * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced APIs, Subscriptions, and Surface Map * Introduced API subscriptions for easier integration and management * Added Surface Map API with improved navigation for better visibility * Expanded surface and vulnerability APIs with watchlist support * Improved scan time display and overall interface consistency ### Improved Navigation and Enterprise Search Enhancements * Enhanced header with refined enterprise search and clearer billing filters * Streamlined enterprise switching for smoother account transitions * Added new indicators and brand menu for better visibility and control * General performance and stability improvements across the platform ### Improved Enterprise Switching and Reliability * Enhanced enterprise account switching for a smoother experience * Improved error handling to reduce interruptions and ensure stability * Minor performance refinements for faster, more reliable workflows * Improved overall product stability and reliability ### Backend improvements * Added new billing filters for easier account management * Refined subscription handling for smoother plan updates * Improved date range formatting and clearer subscription type labels ### Improved Billing, Security, and Developer Experience * **Simplified billing management:** New tools and clearer UI for managing billing, quotas, and access * **Enhanced security settings:** Updated interface and improved user experience * **Better developer tools:** Updated API documentation for smoother integrations ### Developer Mode release with usability and export improvements * Released Developer Mode for advanced security exploration workflows * Improved navigation and overall usability across key product areas * Smoother interactions in frequently used screens * Improved reporting and export usability ### Enterprise API setup improvements * Improved enterprise ID handling in API integration settings * More reliable request behavior during integration setup * Smoother configuration experience for API administrators ### Watchlist and monitoring improvements and reporting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reporting and export usability ### API docs and access reliability improvements * Improved availability of API reference artifacts for integrators * Better consistency when loading integration resources * Smoother developer experience during API implementation ### Expanded API integration coverage * Improved API documentation coverage for integration use cases * Easier access to integration resources for implementation teams * Better clarity when validating supported integration paths ### Integration stability improvements * Improved reliability for API integration traffic handling * Better diagnostics support for troubleshooting integration issues * Smoother overall experience for connected applications ### Integration security and access improvements * Improved cross-origin access controls for safer integrations * Better protection for API integrations used across environments * More consistent behavior for authenticated integration requests ### Account security improvements and monitoring enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved watchlist management and indicator handling ### Performance and reliability improvements and security enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Strengthened account access and verification flows ### Threat intelligence experience improvements and performance updates * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information * Improved product responsiveness across key pages ### Watchlist and monitoring improvements and intelligence enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved threat intelligence views and data clarity ### Watchlist and monitoring improvements and security enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Strengthened account access and verification flows ### Performance and reliability improvements and alerting enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved reliability of notifications and alerts ### Notification and alerting improvements * Improved reliability of notifications and alerts * Better clarity when tracking important updates * More consistent alert behavior across product areas ### Account security improvements and reporting enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved reporting and export usability ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Reporting and export improvements and performance updates * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation * Improved product responsiveness across key pages ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Watchlist and monitoring improvements and performance updates * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved product responsiveness across key pages ### Reporting and export improvements * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation ### Performance and reliability improvements and localization updates * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved multilingual experience and terminology consistency ### Threat intelligence experience improvements * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information # Exposure intelligence Source: https://docs.defendis.com/userguide/en/modules/exposure-intelligence Track internet-facing assets and vulnerabilities. Use `Exposure` to identify weaknesses in internet-facing infrastructure before attackers exploit them. ## Recommended workflow 1. Choose the target domain. 2. Review `Subdomains` to validate inventory. 3. Review `Open ports` to identify reachable services. 4. Review `Vulnerabilities` and `CVEs` for risk prioritization. ## Operational tips * Start from asset inventory, then drill down into vulnerabilities. * Use CVE details and references to support remediation planning. * Pivot from CVEs to affected hosts to align ownership quickly. # Leaks intelligence Source: https://docs.defendis.com/userguide/en/modules/leaks-intelligence Investigate exposed credentials, cards, and documents. Use `Data leaks` as your early-warning radar for exposed information linked to your organization. ## Recommended workflow 1. Select the right domain or BIN from the top-right selector. 2. Open `Credential leaks` to investigate exposed accounts. 3. Open `Payment cards` to review leaked card records. 4. Open `Documents` to review potentially sensitive files. 5. Open details for source, timestamp, and recommended actions. ## Operational tips * Prioritize high-risk accounts and trigger resets plus MFA checks. * Export high-priority findings to support incident response workflows. * Keep watchlists updated so matching quality stays high. # Ransomware intelligence Source: https://docs.defendis.com/userguide/en/modules/ransomware-intelligence Monitor victims, groups, and geographic trends. Use `Ransomware` to understand who is being targeted and which groups are active. ## Recommended workflow 1. Set the reporting time range (for example, last 90 days). 2. Open `Victims` to assess a supplier, peer, or target organization. 3. Open `Groups` to review actor profiles and patterns. 4. Open `Countries` to analyze regional concentration and trends. ## Operational tips * Use group profiles for executive and risk briefings. * Use victim timelines to understand campaign evolution. * Track region-specific patterns when your risk model is geography-driven. # Reporting Source: https://docs.defendis.com/userguide/en/modules/reporting Generate and manage exports for stakeholders. Reports turn investigation output into files you can share across security and leadership teams. ## Create a report 1. Go to `Reports` -> `Create report`. 2. Choose a report type (credentials, payment cards, open ports, vulnerabilities, or documents). 3. Select date range and format (`CSV`, `Excel`, `PDF`). 4. Export. ## Manage generated reports Go to `Reports` -> `Generated` to: * Re-download previous reports * Remove obsolete files * Verify your historical export trail ## Notes * Some report types require selecting a specific watchlist indicator first. * Large exports can take longer to complete. # Backup codes Source: https://docs.defendis.com/userguide/en/settings/backup-codes Generate and store emergency MFA backup codes. Backup codes let you sign in when your authenticator app is unavailable. ## Generate backup codes 1. Go to profile -> `Security`. 2. Locate `Multi-factor authentication`. 3. Click `Generate`. 4. Save codes securely offline. Each backup code is single-use. # Maintain watchlists Source: https://docs.defendis.com/userguide/en/settings/maintain-watchlists Keep watchlists accurate and actionable over time. Watchlist quality directly affects intelligence relevance. ## Recommended maintenance practices * Add new domains and assets as soon as they are in use * Update executive records when identity details change * Add new campaign and brand keywords promptly * Remove stale indicators that no longer matter ## Approval and review notes * New indicators may require manual review based on role and policy * Updates to approved indicators can trigger re-review # Manage your authenticator Source: https://docs.defendis.com/userguide/en/settings/manage-authenticator Replace or remove your current MFA authenticator. If you change devices or authenticator apps, update your MFA factor. ## Replace your current factor 1. Go to profile -> `Security`. 2. Disable existing MFA factor. 3. Click `Enroll MFA`. 4. Complete enrollment with the new authenticator app. # Manage sessions Source: https://docs.defendis.com/userguide/en/settings/manage-sessions Review session behavior and sign out from all devices. Session controls help you secure your account when you suspect unauthorized access. ## Sign out everywhere 1. Go to profile -> `Security`. 2. Click `Sign out from all devices`. This action ends active sessions on all devices, including the current one. ## Session timeout Sessions can expire automatically after inactivity. Re-authentication is expected and improves account security. # Members and roles Source: https://docs.defendis.com/userguide/en/settings/members-and-roles Invite users, assign roles, and manage access. Access levels in Defendis: * `Admin`: full workspace management * `Contributor`: collaborate and export, limited settings access * `Guest`: view-only access ## Invite members 1. Go to `Settings` -> `Members`. 2. Click `Invite member`. 3. Enter work email and role. 4. Send invite. You can track invite status and revoke pending invites from the same page. ## Change roles Use the role dropdown next to each member to assign a new role. ## Remove members Select one or more members, then choose `Remove selected`. ## Seat limits If your invite count exceeds subscription seats, request additional seats or remove inactive users before inviting new ones. # Set up MFA Source: https://docs.defendis.com/userguide/en/settings/mfa-setup Enroll multi-factor authentication for your account. MFA adds a second factor on top of your password. ## Enroll MFA 1. Go to profile -> `Security`. 2. Click `Enroll MFA`. 3. Open your authenticator app (for example Google Authenticator, 1Password, Authy). 4. Scan the QR code shown in Defendis. 5. Enter the 6-digit code to confirm. After enrollment, MFA status is shown as enabled. # Notifications Source: https://docs.defendis.com/userguide/en/settings/notifications Configure in-app and email notifications. Notifications centralize important signals across modules. ## Work with your inbox * Filter by type, severity, and timeframe * Open alerts to inspect related records * Mark completed alerts as read ## Configure notification channels Go to profile -> `Notifications` (or `Notification settings`) to choose: * Which alert categories you receive * Which channels to use (in-app, email, or both) Keep critical categories enabled to avoid missing high-priority events. # Passkeys Source: https://docs.defendis.com/userguide/en/settings/passkeys Set up and use a passkey to sign in to Defendis securely without a password or verification code. Passkeys let you sign in to Defendis with your fingerprint, face, device PIN, or screen lock. They are easier to use than passwords and are designed to resist phishing. ## How passkeys protect your account A passkey consists of a cryptographic key pair. The private key stays on your device or in your passkey provider, while Defendis receives only the public key needed to verify your sign-in. * Your fingerprint and face scan are never shared with Defendis. * There is no password or one-time code for an attacker to steal or trick you into entering on a fake site. * Depending on your device, your passkey may sync securely through services such as iCloud Keychain or Google Password Manager. Your password and authenticator app remain available as recovery and alternative sign-in methods. A passkey is sufficient when you choose passkey sign-in; Defendis will not ask for a separate MFA code. ## Add a passkey 1. Sign in to Defendis on a device you trust. 2. Go to **Settings → Account Security → Passkeys**. 3. Select **Add passkey**. 4. Follow your device prompt and confirm with your fingerprint, face, PIN, or screen lock. Do not create a passkey on a public or shared device. Anyone who can unlock that device may be able to use its passkey. ## Sign in with a passkey 1. On the Defendis sign-in page, select **Sign in with a passkey**. 2. Choose the passkey requested by your browser or device. 3. Confirm with your fingerprint, face, PIN, or screen lock. You do not need to enter your password or an authenticator code when the passkey sign-in succeeds. ## Manage your passkeys Open **Settings → Account Security → Passkeys** to review, rename, or remove your passkeys. Use a clear name such as “Work MacBook” or “iPhone” so you can recognize each one later. We recommend adding passkeys on more than one trusted device. If a device is lost, remove its passkey from Defendis and use another passkey, your password, or your recovery method to sign in. ## If passkey setup or sign-in does not work * Update your browser and operating system. * Confirm that a screen lock, fingerprint, face recognition, or device PIN is enabled. * Cancel the device prompt and try again. * Try another supported browser or a different trusted device. * If your passkey is unavailable, sign in with your password and complete any required verification. Passkeys require a compatible browser and device. They are not available for accounts that sign in exclusively through single sign-on (SSO). # Profile and preferences Source: https://docs.defendis.com/userguide/en/settings/profile-and-preferences Update personal profile details, language, and theme. Use personal account settings to control your identity and UI preferences. ## Update profile details * Go to your profile -> `Personal account` * Update first name, last name, phone number, and username ## Upload your avatar * Open the `Avatar` section * Upload a PNG or JPEG image under 5 MB ## Choose language and theme * Set interface language or use `Auto` * Set `Light`, `Dark`, or `Auto` theme mode Changes save automatically and apply across your Defendis workspaces. # Recover your password Source: https://docs.defendis.com/userguide/en/settings/recover-password Reset your password when you cannot sign in. If you cannot access your account: 1. Open the login page. 2. Click `Forgot password`. 3. Enter your work email. 4. Open the reset link from your inbox. 5. Set a new password. After successful reset, sign in again with your new password. # Sign in with MFA Source: https://docs.defendis.com/userguide/en/settings/sign-in-with-mfa Understand the login flow when MFA is enabled. When MFA is enabled, each sign-in requires your current 6-digit code. ## Sign-in flow 1. Enter email and password. 2. Provide 6-digit authenticator code. 3. Access your workspace. If MFA is not configured, Defendis can use one-time email verification depending on your setup. # Watchlist basics Source: https://docs.defendis.com/userguide/en/settings/watchlist-basics Watchlists are the foundation of scoped monitoring in Defendis. They let you track indicators such as domains, assets, executives, keywords, and payment cards. When new intelligence matches a watchlist indicator, Defendis can trigger alerts so your team can respond quickly. The number of indicators you can add depends on your subscription. # Watchlist types Source: https://docs.defendis.com/userguide/en/settings/watchlist-types Learn what each watchlist type is used for. Defendis supports multiple watchlist types: * `Assets`: monitor vulnerabilities affecting vendor/product/version combinations * `Keywords`: monitor dark web and social mentions of brand terms * `Domains`: monitor suspicious domains and phishing-related activity * `BINs`: monitor payment-card exposure signals * `Executives`: monitor mentions and impersonation signals for leadership * `Ransomware groups`: follow activity from selected groups Use bulk import when you need to add many indicators efficiently. # Workspace settings Source: https://docs.defendis.com/userguide/en/settings/workspace-settings Manage workspace-level branding and organization information. Workspace settings define how your organization appears in Defendis. ## What you can update * Workspace logo (PNG or JPEG under 5 MB) * Workspace information, when editable ## If fields are read-only Some workspace fields are admin-restricted or support-managed. * Contact your workspace admin for permission-related changes * Contact support at `support@defendis.com` for support-managed updates # Complete your onboarding Source: https://docs.defendis.com/userguide/en/start/complete-your-onboarding Finish initial account setup after your invitation. Access to Defendis is invite-only. After your invitation, complete onboarding to activate your workspace access. ## Set your password Choose a strong password with: * At least 8 characters * Uppercase and lowercase letters * Numbers and symbols ## Personalize your account Add profile details so your teammates can identify you quickly: * First and last name * Username ## Understand session behavior You stay signed in for up to 24 hours unless: * You sign out manually * You sign in from another device # Getting started Source: https://docs.defendis.com/userguide/en/start/getting-started Take the first actions that produce value quickly. Use this checklist right after your first sign-in. ## 1) Secure your account * Go to profile -> `Security` * Click `Enroll MFA` * Scan the QR code with your authenticator app * Enter the current 6-digit code ## 2) Add your first watchlist indicators Watchlists define what Defendis should monitor for your organization. * Go to profile -> `Watchlists` * Click `Add indicator` * Add a domain, IP, asset, executive, keyword, or BIN * Save Depending on your role, the indicator may be approved immediately or reviewed first. ## 3) Explore intelligence modules * Start with broad filters in `Data leaks`, `Exposure`, or `Ransomware` * Open rows and cards to review source context and recommendations * If you monitor multiple domains, use the domain selector to switch context ## 4) Export your first report * Go to `Reports` -> `Create report` * Select report type and date range * Choose export format (`CSV`, `Excel`, or `PDF`) * Export # Introduction to Defendis Source: https://docs.defendis.com/userguide/en/start/introduction-to-defendis Defendis helps security teams monitor external threat signals and turn findings into action. With Defendis, you can: * Monitor leaked credentials, documents, and payment-card signals * Track external exposure across subdomains, ports, and vulnerabilities * Follow ransomware actor and victim activity * Build reports for leadership and operational teams By the end of your onboarding, you should be able to: * Set up your account and security basics * Add watchlist indicators relevant to your organization * Navigate modules and investigate findings * Export reports for stakeholders # Navigating Defendis Source: https://docs.defendis.com/userguide/en/start/navigating-defendis Understand the main workspace areas and how to move between them. The Defendis workspace has three core navigation areas. ## Main menu Use the main menu to move between modules such as: * Data leaks * Exposure * Ransomware * Reports If your organization monitors multiple domains, use the domain selector in the top-right corner. ## Tabs panel Each module includes tabs that let you switch views and refine data with filters such as: * Time range * Severity * Status * Search queries ## Insights area This is where your data appears and where you take action. * Open rows and cards for detailed context * Use dashboards for quick pivots into module-specific insights # Supported browsers Source: https://docs.defendis.com/userguide/en/start/supported-browsers Browsers currently supported by the Defendis web app. Defendis currently supports: * Chrome 111+ * Safari 16.3+ * Firefox 112+ * Microsoft Edge 112+ * Opera 98+ # FAQ Source: https://docs.defendis.com/userguide/en/troubleshooting/faq Common questions about access, watchlists, reporting, and support. # FAQ ## Access and authentication Double-check your email and password. If needed, use password reset from the login page. If you were previously active, your session may have expired and you need to sign in again. Go to profile -> `Security`, then click `Enroll MFA`, scan the QR code, and confirm with a 6-digit code. Ensure your device time is set automatically, because MFA codes are time-based. If the issue continues, use a backup code or ask an admin to help reset your factors. Go to profile -> `Security` -> backup codes, generate a set, and store them securely offline. Go to profile -> `Security`, disable the current factor, and enroll MFA again with the new app. Session expiry is a security control and can also happen when you sign in from another device. ## Permissions and members Your role likely does not include permission for that page or action. Ask an admin to review your role. Open `Settings` -> `Members`, click `Invite member`, enter work email, assign role, and send. Only admins can invite members. Ask an admin to review your role and role-based permissions in workspace settings. ## Watchlists and data visibility Open `Settings` -> `Watchlists`, choose the relevant tab, click `Add indicator`, complete details, and save. New or updated indicators can trigger manual review to validate authorized and compliant monitoring. Use the domain selector in the top-right. Pages refresh automatically to the selected domain context. Confirm watchlists contain the expected indicators and clear filters that might be hiding data. ## Reports and exports Yes. Go to `Reports` -> `Create report`, choose type, date range, format, and export. Some report types require a selected indicator first. Export permissions can also depend on role and subscription. `CSV`, `Excel`, and `PDF`. Go to `Reports` -> `Generated` to re-download or delete previous exports. ## Alerts and support Open `Notifications` to view and filter alerts by type, date, and context. Go to profile -> `Notifications` (or notification settings) and choose categories and channels. MFA is strongly recommended to reduce account takeover risk. Use the in-app support chat icon to contact the Defendis support team. # Create asset Source: https://docs.defendis.com/api-reference/assets-watchlist/create-asset /openapi.json post /api/v1/watchlists/assets # Delete assets Source: https://docs.defendis.com/api-reference/assets-watchlist/delete-assets /openapi.json post /api/v1/watchlists/assets/delete # List assets Source: https://docs.defendis.com/api-reference/assets-watchlist/list-assets /openapi.json get /api/v1/watchlists/assets # Update asset Source: https://docs.defendis.com/api-reference/assets-watchlist/update-asset /openapi.json put /api/v1/watchlists/assets/{id} # Create BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/create-bin /openapi.json post /api/v1/watchlists/bin Creates a BIN in the current enterprise watchlist. # Delete BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/delete-bins /openapi.json post /api/v1/watchlists/bin/delete # List BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/list-bins /openapi.json get /api/v1/watchlists/bin # Update BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/update-bin /openapi.json put /api/v1/watchlists/bin/{id} # Credentials (domain) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-domain /openapi.json get /api/v1/dataleaks/credentials # Credentials (email) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-email /openapi.json get /api/v1/dataleaks/credentials/email # Dataleaks stats Source: https://docs.defendis.com/api-reference/dataleaks/dataleaks-stats /openapi.json get /api/v1/dataleaks/stats # Documents (domain) Source: https://docs.defendis.com/api-reference/dataleaks/documents-domain /openapi.json get /api/v1/dataleaks/documents # Payment Cards Source: https://docs.defendis.com/api-reference/dataleaks/payment-cards /openapi.json get /api/v1/dataleaks/paymentcards/bins # Victim profile Source: https://docs.defendis.com/api-reference/dataleaks/victim-profile /openapi.json get /api/v1/dataleaks/user # Create domain Source: https://docs.defendis.com/api-reference/domains-watchlist/create-domain /openapi.json post /api/v1/watchlists/domain Creates a domain in the current enterprise watchlist. # Delete domains Source: https://docs.defendis.com/api-reference/domains-watchlist/delete-domains /openapi.json post /api/v1/watchlists/domain/delete # List domains Source: https://docs.defendis.com/api-reference/domains-watchlist/list-domains /openapi.json get /api/v1/watchlists/domain # Update domain Source: https://docs.defendis.com/api-reference/domains-watchlist/update-domain /openapi.json put /api/v1/watchlists/domain/{id} # Create executive Source: https://docs.defendis.com/api-reference/executives-watchlist/create-executive /openapi.json post /api/v1/watchlists/executive # Delete executives Source: https://docs.defendis.com/api-reference/executives-watchlist/delete-executives /openapi.json post /api/v1/watchlists/executive/delete # List executives Source: https://docs.defendis.com/api-reference/executives-watchlist/list-executives /openapi.json get /api/v1/watchlists/executive # Update executive Source: https://docs.defendis.com/api-reference/executives-watchlist/update-executive /openapi.json put /api/v1/watchlists/executive/{id} # CVE details Source: https://docs.defendis.com/api-reference/exposure/cve-details /openapi.json get /api/v1/exposure/cves/{id} # CVEs Source: https://docs.defendis.com/api-reference/exposure/cves /openapi.json get /api/v1/exposure/cves # DNS records Source: https://docs.defendis.com/api-reference/exposure/dns-records /openapi.json get /api/v1/exposure/dns # Hosts Source: https://docs.defendis.com/api-reference/exposure/hosts /openapi.json get /api/v1/exposure/hosts # JavaScript findings Source: https://docs.defendis.com/api-reference/exposure/javascript-findings /openapi.json get /api/v1/exposure/js # Ports Source: https://docs.defendis.com/api-reference/exposure/ports /openapi.json get /api/v1/exposure/ports # Subdomains Source: https://docs.defendis.com/api-reference/exposure/subdomains /openapi.json get /api/v1/exposure/subdomains # Surface vulnerabilities Source: https://docs.defendis.com/api-reference/exposure/surface-vulnerabilities /openapi.json get /api/v1/exposure/vulnerabilities # Health Source: https://docs.defendis.com/api-reference/health/health /openapi.json get /health # Create keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/create-keyword /openapi.json post /api/v1/watchlists/keyword Creates a keyword in the current enterprise watchlist. # Delete keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/delete-keywords /openapi.json post /api/v1/watchlists/keyword/delete # List keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/list-keywords /openapi.json get /api/v1/watchlists/keyword # Update keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/update-keyword /openapi.json put /api/v1/watchlists/keyword/{id} # Create ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/create-ransom-group /openapi.json post /api/v1/watchlists/ransom # Delete ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/delete-ransom-groups /openapi.json post /api/v1/watchlists/ransom/delete # List ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/list-ransom-groups /openapi.json get /api/v1/watchlists/ransom # Update ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/update-ransom-group /openapi.json put /api/v1/watchlists/ransom/{id} # Group details Source: https://docs.defendis.com/api-reference/ransomware/group-details /openapi.json get /api/v1/ransom/groups/{id} # Groups Source: https://docs.defendis.com/api-reference/ransomware/groups /openapi.json get /api/v1/ransom/groups # Ransomware stats Source: https://docs.defendis.com/api-reference/ransomware/ransomware-stats /openapi.json post /api/v1/ransom/stats # Victims Source: https://docs.defendis.com/api-reference/ransomware/victims /openapi.json get /api/v1/ransom/victims # Victims (by country) Source: https://docs.defendis.com/api-reference/ransomware/victims-by-country /openapi.json get /api/v1/ransom/country/victims # Create group Source: https://docs.defendis.com/api-reference/watchlists/create-group /openapi.json post /api/v1/watchlists/create # Delete groups Source: https://docs.defendis.com/api-reference/watchlists/delete-groups /openapi.json post /api/v1/watchlists/delete # Group stats Source: https://docs.defendis.com/api-reference/watchlists/group-stats /openapi.json get /api/v1/watchlists/stats # List groups Source: https://docs.defendis.com/api-reference/watchlists/list-groups /openapi.json get /api/v1/watchlists # Update group Source: https://docs.defendis.com/api-reference/watchlists/update-group /openapi.json put /api/v1/watchlists/{id} # Authentication Source: https://docs.defendis.com/api/auth Defendis API uses bearer API keys for authentication and enterprise scope for authorization. ## API key Send your API key in the `Authorization` header for all customer endpoints under `/api/v1/*`: ```http theme={null} Authorization: Bearer ``` ```bash theme={null} #Example request: curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## API key lifecycle API keys are created and managed in [Defendis web app](https://app.defendis.com). Use unique keys per integration (SIEM, data lake ingestion, SOAR automation). Rotate keys on a schedule (every 60 to 90 days) and immediately after any suspected exposure. Revoke unused keys promptly to reduce your exposure. ## Authorisation scope Each API key is bound to a workspace scope. The API enforces access to workspace-owned resources and input validation for scoped endpoints. Out-of-scope requests will return 403 Forbidden Dataleaks endpoints are intentionally strict to prevent data leakage: * Requests require scoped inputs (`domain`, `email`, or `bin` depending on endpoint). * Missing required scoped parameters return 400 Bad Request. * Out-of-scope inputs return 403 Forbidden.. * Enterprise billing access restrictions may also return 403 Forbidden on protected routes. ## Common failures ```http theme={null} # Missing API key HTTP/1.1 401 Unauthorized { "error": "Missing API key" } ``` ```http theme={null} # Invalid or revoked API key HTTP/1.1 401 Unauthorized { "error": "Invalid or revoked API key" } ``` ## Securing your integration These recommendations cover the minimum security and observability controls we expect for production integrations, including secrets handling, least-privilege access, and request correlation: Store API keys in a secret manager, never in source control or client-side code. Restrict key access to only the workloads that need it. Never log the full Authorization header. Capture `x-request-id` response header to speed up investigations. # Deployment Source: https://docs.defendis.com/api/deployment This page explains how the Defendis API evolves over time: versioning guarantees, compatibility expectations, and the practices you should follow to keep production integrations stable. ## Versioning policy Defendis uses path-based versioning. Current customer API is `/api/v1` ### Backward-compatible changes We may introduce backward-compatible improvements without changing the version, including: Adding new endpoints. Adding new optional query parameters. Adding new fields to existing responses. For forward compatibility, ignore unknown response fields and avoid strict JSON parsing that fails on additional properties. ### Breaking changes Breaking changes will be introduced under a new version prefix `/api/v2`. # endpoints Source: https://docs.defendis.com/api/endpoints This page gives you a practical map of which endpoint families exist, what they’re used for, and how they fit together in a real integration. ## Recommended integration flow Most customer integrations follow this pattern: Use watchlists to define scope (domains, keywords, BINs, executives, assets). Query Dataleaks, Exposure, and Ransomware datasets with scoped inputs. Ingest incrementally using pagination and date windows where supported. Normalize and correlate results into downstream systems such as SIEM, SOAR, a data lake, or case management. ## Response envelope Successful responses use a consistent top-level envelope: ```json title="Single resource" theme={null} { "data": { "...": "..." } } ``` ```json title="List endpoints" theme={null} { "data": [{ "...": "..." }], "paging": { "...": "..." } } ``` ```json title="Batch delete" theme={null} { "data": { "count": 3 } } ``` ## Health Use this for basic connectivity checks (no auth required): ```bash title="Health request" theme={null} curl -sS "https://api.defendis.com/health" ``` ## Watchlists Watchlists are the foundation of authorization scope. * `GET /api/v1/watchlists` * `POST /api/v1/watchlists/create` * `PUT /api/v1/watchlists/{id}` * `POST /api/v1/watchlists/delete` * `GET /api/v1/watchlists/stats` * `GET /api/v1/watchlists/assets` * `POST /api/v1/watchlists/assets` * `PUT /api/v1/watchlists/assets/{id}` * `POST /api/v1/watchlists/assets/delete` * `GET /api/v1/watchlists/domain` * `POST /api/v1/watchlists/domain` * `PUT /api/v1/watchlists/domain/{id}` * `POST /api/v1/watchlists/domain/delete` * `GET /api/v1/watchlists/bin` * `POST /api/v1/watchlists/bin` * `PUT /api/v1/watchlists/bin/{id}` * `POST /api/v1/watchlists/bin/delete` * `GET /api/v1/watchlists/executive` * `POST /api/v1/watchlists/executive` * `PUT /api/v1/watchlists/executive/{id}` * `POST /api/v1/watchlists/executive/delete` * `GET /api/v1/watchlists/keyword` * `POST /api/v1/watchlists/keyword` * `PUT /api/v1/watchlists/keyword/{id}` * `POST /api/v1/watchlists/keyword/delete` * `GET /api/v1/watchlists/ransom` * `POST /api/v1/watchlists/ransom` * `PUT /api/v1/watchlists/ransom/{id}` * `POST /api/v1/watchlists/ransom/delete` Many list endpoints accept an optional `watchlistid` query parameter, and batch-delete endpoints use a JSON request body with an `ids` array. `POST /api/v1/watchlists/domain`, `POST /api/v1/watchlists/keyword`, and `POST /api/v1/watchlists/bin` can return: * `403 Forbidden` when enterprise billing access is denied. * `409 Conflict` when the corresponding workspace quota is reached (`quota_domains_reached`, `quota_keywords_reached`, `quota_bins_reached`). ## Modules * `GET /api/v1/dataleaks/credentials` // requires `domain` * `GET /api/v1/dataleaks/credentials/email` // requires `email` * `GET /api/v1/dataleaks/documents` // requires `domain` * `GET /api/v1/dataleaks/paymentcards/bins` // requires `bin` * `GET /api/v1/dataleaks/stats` // requires `domain` * `GET /api/v1/dataleaks/user` // requires `id` * `GET /api/v1/exposure/cves` * `GET /api/v1/exposure/subdomains` * `GET /api/v1/exposure/hosts` // requires `domainId` * `GET /api/v1/exposure/ports` * `GET /api/v1/exposure/vulnerabilities` Start with `subdomains` and `hosts` to build inventory, then use `ports` and `vulnerabilities` for risk triage and reporting. * `POST /api/v1/ransom/stats` // overview stats and trends * `GET /api/v1/ransom/groups` // actor and group listing * `GET /api/v1/ransom/groups/{id}` // group details * `GET /api/v1/ransom/victims` // victim activity listing * `GET /api/v1/ransom/country/victims` // victim activity by country # Errors Source: https://docs.defendis.com/api/errors Defendis API uses standard HTTP status codes and a JSON error envelope. This page explains how to handle errors safely in production, including which scenarios are retryable. ## Error response format Most error responses use this shape: ```json theme={null} { "error": "string", "message": "string (optional)" } ``` Implementation principles: Treat error as a human-readable reason, not a stable enum. Ignore unknown response fields for forward compatibility. Never log secrets, especially the `Authorization` header. ## Status codes and retry actions | Status code | Meaning | Retry strategy | Recommended action | | ----------------------- | ----------------------------------------------------- | -------------- | ---------------------------------------------------------------- | | `400 Bad Request` | Missing or invalid parameters/JSON body | No | Fix request shape or required inputs | | `401 Unauthorized` | Missing, invalid, or revoked API key | No | Validate credentials and replace/re-enable key | | `403 Forbidden` | Authenticated but blocked by enterprise access policy | No | Verify enterprise scope/eligibility and enterprise billing state | | `409 Conflict` | Workspace quota reached on write operations | No | Reduce usage or increase workspace quotas, then retry | | `404 Not Found` | Unknown endpoint or resource | No | Confirm endpoint path, method, and resource identifiers | | `429 Too Many Requests` | Rate limit exceeded | Yes | Retry with exponential backoff + jitter | | `500/502/503/504` | Transient server-side failure | Conditional | Retry safe requests (`GET`) with backoff | ## Common examples | Scenario | HTTP status | Example error body | | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | Missing API key | `401 Unauthorized` | `{ "error": "Missing API key" }` | | Out-of-scope request | `403 Forbidden` | `{ "error": "You don't have permission to view this" }` | | Enterprise billing access denied | `403 Forbidden` | `{ "error": "Enterprise billing access denied", "reason": "payment_unpaid", "status": "unpaid" }` | | Watchlist quota reached | `409 Conflict` | `{ "error": "quota_domains_reached", "metric": "domains", "used": 10, "limit": 10, "requestedIncrement": 1 }` | | Rate limit exceeded | `429 Too Many Requests` | `{ "error": "Rate limit exceeded" }` | ### Backoff snippet ```js title="JavaScript backoff snippet" theme={null} function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); } async function fetchGetWithBackoff(url, options = {}, { maxRetries = 5, baseDelayMs = 500 } = {}) { const retryableStatuses = new Set([429, 500, 502, 503, 504]); for (let attempt = 0; attempt <= maxRetries; attempt++) { try { const res = await fetch(url, { ...options, method: "GET" }); if (!retryableStatuses.has(res.status)) return res; if (attempt === maxRetries) return res; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } catch (error) { if (attempt === maxRetries) throw error; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } } } ``` ```python title="Python backoff snippet" theme={null} import random import time import requests def get_with_backoff(url, headers, max_retries=5, base_delay_s=0.5, timeout_s=30): retryable_statuses = {429, 500, 502, 503, 504} for attempt in range(max_retries + 1): try: resp = requests.get(url, headers=headers, timeout=timeout_s) except requests.RequestException: if attempt == max_retries: raise resp = None if resp is not None and resp.status_code not in retryable_statuses: return resp if attempt == max_retries: return resp delay = min(30.0, base_delay_s * (2 ** attempt)) jitter = random.uniform(0, 0.25) time.sleep(delay + jitter) ``` ## Troubleshooting checklist When contacting Support, include: Include the request path `example: /api/v1/dataleaks/stats` Include the UTC timestamp and your client request ID. Include the HTTP status code and the error response body. Include the parameters you sent, with sensitive values redacted. # Getting Started Source: https://docs.defendis.com/api/getting-started This guide helps you make your first successful request to the Defendis API and adopt conventions that make your integration reliable in production. ## Quickstart ```http theme={null} curl -sS "https://api.defendis.com/health" ``` ```http theme={null} #Expected response: { "status": "ok" } ``` ```bash theme={null} export DEFENDIS_API_KEY="YOUR_API_KEY" ``` ```bash theme={null} curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## Core concepts ### Watchlists Datasets in Defendis are access-controlled by your workspace scope. In practice: * You define watchlists that represent what you are authorised to monitor (`domains`, `emails`, `keywords`, `BINs`, and other assets). * Many endpoints validate input against your watchlist scope. * Requests outside your approved scope return 403 Forbidden. * Watchlist write endpoints may return 409 Conflict when your workspace quota is reached. ### Contract-first integration * The OpenAPI spec is the source of truth for endpoints, parameters, and request/response schemas: `../openapi.yaml`. * If you generate clients, treat the API as additive: new fields may appear without warning. Your parser should ignore unknown fields. ## Request conventions ### Content types * Use query parameters for filtering and pagination on endpoints that support them. * When an endpoint accepts a request body, send JSON: ```http theme={null} Content-Type: application/json ``` For more information, see [Errors](/api/errors) and [Endpoints](/api/endpoints). ### Pagination Paginated list endpoints return a consistent envelope: * `data`: array of records * `paging`: pagination metadata with: * `currentPage` * `pageSize` * `totalRecords` * `totalPages` * `hasMore` * `nextPage` Recommended ingestion loop: * Start with `page=1`. * Keep fetching until `paging.hasMore` is `false` (or `paging.nextPage` is `null`). * Persist checkpoints (page and filter window) so your ingestion can resume safely after failures. ```json title="Example" theme={null} { "data": [], "paging": { "currentPage": 1, "pageSize": 50, "totalRecords": 120, "totalPages": 3, "hasMore": true, "nextPage": 2 } } ``` ### Date filters Some endpoints support date window filtering. When supported, use a closed-open window: * `fromDate`: inclusive lower bound * `toDate`: exclusive upper bound Date parameters are standardized as `fromDate` and `toDate`. Always follow the endpoint’s reference docs / OpenAPI contract for exact support. Client recommendation: * Use `YYYY-MM-DD` for date-only filters. * Prefer narrow windows for high-volume pulls and widen gradually. ### Search & sorting Search and sorting are endpoint-specific. Common patterns include: * `search` * `sortBy` * `sortOrder` When omitted, server-side defaults apply. Use the OpenAPI contract and the endpoint reference docs to confirm supported parameters and allowed values. ## Rate limits & reliability Defendis enforces rate limiting. When exceeded you will receive 429 Too Many Requests. Client best practices: * Use exponential backoff for retries (with jitter). * Distribute polling workloads over time. * Automatically retry **safe** requests (GET) on transient failures (`429`, `5xx`, timeouts). * Avoid retrying non-idempotent writes unless your application guarantees idempotency. ## Typical integration patterns ### Pull model Configure watchlists so your integration only pulls data within approved scope. Ingest Dataleaks, Exposure, and Ransomware datasets on a recurring schedule. Map results into your SIEM/SOAR, data lake, or case management schema. ### Near-real-time workflows For operational workflows, use frequent polling with small time windows and robust retry/backoff behavior. ## Data handling & privacy Some datasets, especially `Dataleaks`, may contain sensitive information. As an API consumer, you are responsible for ensuring the data is handled appropriately within your environment. Recommended practices: Keep only the fields and retention window required for your workflow. Limit sensitive dataset access to the smallest set of users and services. Avoid logging full payloads or sensitive fields in application and audit logs. Apply your internal security, legal, and compliance controls to this API data. # Introduction Source: https://docs.defendis.com/api/index Defendis API lets you integrate external threat signals into your product and security workflows to automate monitoring and enrichment. Use this API to: Query data leak signals for approved identifiers (domains, BINs, etc). Create and manage watchlists that define what you monitor. Analyse your external exposure and track ransomware activity. ## Base URL and versioning * Base URL: `https://api.defendis.com` * Version prefix: `/api/v1` Example endpoint: `https://api.defendis.com/api/v1/watchlists` ## Authentication All `/api/v1/*` endpoints require an API key: ```http theme={null} Authorization: Bearer ``` ## Start here Make your first request and learn integration patterns. API keys, authorization scope, and security best practices. Guidance on which endpoint family to use, with OpenAPI reference. Error model, retry behavior, and troubleshooting. Availability, versioning policy, and change management. ## Downloads * Download the `Postman file` * Import the OpenAPI spec URL: `https://api.defendis.com/openapi.json` # Changelog Source: https://docs.defendis.com/changelog ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Navigation and usability improvements and integration enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved API integration access and configuration flows ### Navigation and usability improvements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks ### Navigation and usability improvements and alerting enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved reliability of notifications and alerts ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Integration access and developer experience improvements and security enhancements * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding * More reliable behavior for enterprise integration scenarios * Strengthened account access and verification flows ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Service‑Provider Billing & Workspace Improvements * Introduced service‑provider‑managed billing for more flexible workspace payments * Enhanced billing breakdowns for clearer cost visibility * Improved signup and verification flow for a smoother onboarding experience * Fixed minor issues and refreshed documentation pages for better clarity ### Improved Billing * Enhanced billing management * General refinements for better reliability and maintainability ### Enhanced Billing, Security, and Workspace Controls * *Stronger account security:* Refined MFA and session handling to ensure smoother, more reliable authentication * Strengthened account access and verification flows ### Improved Access and reliability * Enhanced subscription permission checks for smoother access * Improved overall product stability and reliability ### Improved Trial License and Billing Display * Clearer display of billing amounts for all license types * Enhanced handling of trial licenses for a smoother experience * More accurate and transparent billing information throughout the app * Improved overall product stability and reliability ### Improved Reliability for Authentication Requests * Extended retry window for temporary authentication issues to reduce login interruptions * Enhances overall stability when network conditions are inconsistent * Provides a smoother sign-in experience with fewer transient errors * Improved overall product stability and reliability ### Improved Session Stability and Refresh Handling * Enhanced session handling ensures smoother reconnections and fewer interruptions * Provides a more reliable and consistent experience when working across multiple sessions * Strengthened account access and verification flows ### Improved Stability and Minor Enhancements * Enhanced overall app stability for a smoother experience * Fixed minor issues to improve reliability and performance * Optimized background processes for faster response times * Improved overall product stability and reliability ### Improved Billing, Authentication, and Subscription Experience * Smarter billing: Introduces catalog-based billing with flexible, document-level discounts * Smoother sign-in: Enhanced authentication retry flow and refined interface for better usability * Faster loading: Updated loading visuals and automatic fallback for terminal licenses ### Improved Billing and Access Experience * Enhanced billing workflows for greater accuracy and reliability * Streamlined access controls to ensure smoother user management * Minor performance and stability improvements across the platform * Improved API integration access and configuration flows ### Improved Deployment Security and Performance * Enhanced deployment process with secure Google Cloud integration * Improved reliability through updated service account management * Improved reliability of notifications and alerts * Better clarity when tracking important updates ### Improved Security, Streaming, and Workspace Controls * Enhanced session management with new logout options and smoother refresh handling * Strengthened workspace access controls with billing fallback for uninterrupted service * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced Member Notifications in Console * Introduces a new notifications feature for console members * Enables real-time updates and alerts directly within the console * Improves visibility and responsiveness for team activities * Delivers a smoother, more connected user experience ### Improved Billing, Permissions, and Workspace Management * Enhanced billing experience with new payment form states and improved Stripe integration * Added permission catalog service for more flexible access control * Improved workspace management with safer deletion and new catalog features * Improved API integration access and configuration flows ### Improved Workspace Experience * Introduced enhanced workspace management with clearer allocation and usage controls * Improved user and billing management capabilities for workspace administrators * Improved navigation and overall usability ### Improved Workspace Management and Onboarding * Introduced user verification and guided onboarding sessions for a smoother start * Enhanced invite acceptance and redirect flow for a more seamless joining experience * Improved session reliability and visual alignment in the header ### Improved Data Security and Billing Reliability * General stability and performance enhancements for smoother operations * Improved overall product stability and reliability * Enhanced usability across key product areas ### Improved Workspace Billing Sync * Reduces potential discrepancies in billing information * Provides a smoother experience when managing workspace billing changes * Improved navigation and overall usability ### Improved Search Efficiency and Workspace Access Alignment * Search updates are now faster and more responsive, reducing unnecessary refreshes * Overall experience is smoother with improved performance and reliability * Improved product responsiveness across key pages ### Improved Workspace Insights and Session Reliability * Enjoy smoother session experiences with enhanced refresh handling * Improved reliability and control for workspace management tasks * Improved API integration access and configuration flows ### Performance and Stability Improvements * Enhanced overall app responsiveness for a smoother experience * Improved reliability to reduce unexpected errors * Minor interface refinements for better usability * General maintenance updates to keep things running efficiently ### Workspace Stability Improvements * Improved handling of approved workspace differences to reduce unnecessary alerts * General stability and performance enhancements for smoother workspace operations * Improved navigation and overall usability ### Improved Enterprise Billing Accuracy and Data Access * Improved data retrieval for faster and more reliable billing information * Streamlined reconciliation process to reduce potential discrepancies * Improved overall product stability and reliability ### Improved Billing Options and License Sync * Added support for a **Free** billing status to simplify account management * Workspaces now automatically **synchronize license details**, ensuring accurate and up‑to‑date access * Enhancements improve transparency and reduce manual updates for workspace admins * Improved navigation and overall usability ### Improved Workspace Licensing and Error Handling * Introduced enhanced workspace licensing with updated data models * Improved reliability through better error handling and duplicate prevention * Streamlined membership updates to maintain consistency and accuracy * Refreshed documentation pages for clearer guidance ### Improved Reports * Generate reports with your enterprise avatar and default logo for a more personalized look * Analytics now automatically adapts to your region for more accurate insights * Improved export usability ### Improved reliability for notification counts * Notification counts now update more consistently, even in unstable network conditions * Enhanced error handling ensures smoother user experience when fetching notifications * Overall reliability and responsiveness of notifications have been improved ### Enhanced Authentication * Improved sign-in reliability with updated authentication flow * Provides a smoother and more secure reauthentication experience for users * Strengthened account access and verification flows ### Improved API and Watchlist Management * Added enterprise ID support to API calls for better integration and control * Enhanced watchlist domain management for more accurate tracking * Improved CVE asset matching to strengthen vulnerability insights * Improved API integration access and configuration flows ### Improved app stability, CVE Tools, and Ransomware Insights * Enhanced authentication, Improved performance, and clearer error feedback * Added ransomware victim summaries, detailed views, and country-based filtering for deeper insights * Strengthened account access and verification flows ### Improved Error Handling and Watchlist Enhancements * Enhanced watchlist functionality with enterprise-grade validation * Improved overall stability and consistency across the platform * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Improved performance and simplified app behavior * Streamlined app configuration for faster load times * Reduced unnecessary redirects to improve navigation * Enhanced reliability and consistency across user sessions * Improved navigation and overall usability ### Improved Authentication and Session Reliability * Added automatic redirection to help users recover sessions after cutover events * Enhanced session handling for smoother, more reliable sign-ins * Improved overall stability and continuity during authentication transitions * Strengthened account access and verification flows ### Improved Resource Management with Custom Cache Controls * Enhanced performance through smarter caching behavior * Faster load times and reduced redundant data requests * More consistent user experience when accessing stored resources * Improved navigation and overall usability ### Improved API performance and reliability * Enhanced API responsiveness with smarter rate limiting for task updates * Improved connection stability to ensure smoother, more consistent interactions * Delivers a faster and more reliable experience for high-volume API users * Improved API integration access and configuration flows ### Improved Task Status Tracking and Batch Updates * Enjoy more accurate and consistent task progress updates * Benefit from smoother monitoring of large-scale task operations * Improved API integration access and configuration flows ### Improved Enterprise Update Experience * Enhanced enterprise update process for smoother data management * General usability improvements for a faster, more reliable experience * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Improved Support Experience and Settings Enhancements * Introduced a new Support Overview for easier access to key support information * Enhanced Support Settings with clearer labels and a more intuitive layout * Streamlined navigation to help users manage support preferences more efficiently * Improved API integration access and configuration flows ### Improved Billing and watchlist management * Past due accounts are now subject to a 7 days grace period * More accurate scope validation and smoother loading states in your watchlist dropdown * Faster, more reliable interactions across tasks management * Improved API integration access and configuration flows ### Improved Chat User Identity and Settings * Enhanced Chat integration for more accurate user identification * Simplified configuration options for managing communication settings * Improved reliability and consistency in user messaging experiences * Strengthened account access and verification flows ### Improved Task Management and Session Handling * Enhanced task management experience with improved UI and selection tools * Improved session and authentication handling for more reliable logins and logouts ### Improved Dashboard Stability and Error Handling * Enhanced reliability of dashboard statistics display * Improved handling of unexpected data or connection issues * Reduced likelihood of dashboard errors impacting user experience * Improved reporting and export usability ### Improved Session Reliability and Fraud Detection * Enhanced session management for more reliable and secure user experiences * Updated billing documentation for clearer incident response guidance * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages ### Improved Fraud Detail Loading Performance * Faster loading times when viewing fraud details * Smoother experience when switching between fraud cases * Enhanced reliability and consistency in fraud data display * Improved product responsiveness across key pages ### Enhanced Fraud Management and Navigation * Updates fraud tabs and localization for a clearer, more consistent interface * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages * Better readability in user-facing content ### Improved Subscription Stability and Error Handling * Enhanced reliability when managing enterprise subscriptions * Reduced likelihood of subscription errors and interruptions * Improved clarity of error messages for smoother user experience * Improved overall product stability and reliability ### Improved Host Node Display in Surface Maps * Host node visuals now render with consistent width for better clarity * Enhanced readability and alignment across different map views * Minor stability improvements for smoother map interactions * Improved overall product stability and reliability ### Enhanced Feed, Intelligence, and Map Experiences * Introduced a new integrated feed experience with improved performance and real-time updates * Expanded intelligence features with enhanced loading states and new airport country insights * Refreshed map visuals and improved key management for smoother navigation * Added richer surface map details, including DNS summaries and clearer host information ### Easily Delete Workspaces * Added the ability to permanently delete workspaces when no longer needed * Simplifies workspace management and keeps your environment organized * Ensures a smoother experience when cleaning up unused projects * Improved navigation and overall usability ### Integration access and developer experience improvements * Improved API integration to support more reliable connections * Increased overall stability and performance for development operations * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced APIs, Subscriptions, and Surface Map * Introduced API subscriptions for easier integration and management * Added Surface Map API with improved navigation for better visibility * Expanded surface and vulnerability APIs with watchlist support * Improved scan time display and overall interface consistency ### Improved Navigation and Enterprise Search Enhancements * Enhanced header with refined enterprise search and clearer billing filters * Streamlined enterprise switching for smoother account transitions * Added new indicators and brand menu for better visibility and control * General performance and stability improvements across the platform ### Improved Enterprise Switching and Reliability * Enhanced enterprise account switching for a smoother experience * Improved error handling to reduce interruptions and ensure stability * Minor performance refinements for faster, more reliable workflows * Improved overall product stability and reliability ### Backend improvements * Added new billing filters for easier account management * Refined subscription handling for smoother plan updates * Improved date range formatting and clearer subscription type labels ### Improved Billing, Security, and Developer Experience * **Simplified billing management:** New tools and clearer UI for managing billing, quotas, and access * **Enhanced security settings:** Updated interface and improved user experience * **Better developer tools:** Updated API documentation for smoother integrations ### Developer Mode release with usability and export improvements * Released Developer Mode for advanced security exploration workflows * Improved navigation and overall usability across key product areas * Smoother interactions in frequently used screens * Improved reporting and export usability ### Enterprise API setup improvements * Improved enterprise ID handling in API integration settings * More reliable request behavior during integration setup * Smoother configuration experience for API administrators ### Watchlist and monitoring improvements and reporting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reporting and export usability ### API docs and access reliability improvements * Improved availability of API reference artifacts for integrators * Better consistency when loading integration resources * Smoother developer experience during API implementation ### Expanded API integration coverage * Improved API documentation coverage for integration use cases * Easier access to integration resources for implementation teams * Better clarity when validating supported integration paths ### Integration stability improvements * Improved reliability for API integration traffic handling * Better diagnostics support for troubleshooting integration issues * Smoother overall experience for connected applications ### Integration security and access improvements * Improved cross-origin access controls for safer integrations * Better protection for API integrations used across environments * More consistent behavior for authenticated integration requests ### Account security improvements and monitoring enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved watchlist management and indicator handling ### Performance and reliability improvements and security enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Strengthened account access and verification flows ### Threat intelligence experience improvements and performance updates * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information * Improved product responsiveness across key pages ### Watchlist and monitoring improvements and intelligence enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved threat intelligence views and data clarity ### Watchlist and monitoring improvements and security enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Strengthened account access and verification flows ### Performance and reliability improvements and alerting enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved reliability of notifications and alerts ### Notification and alerting improvements * Improved reliability of notifications and alerts * Better clarity when tracking important updates * More consistent alert behavior across product areas ### Account security improvements and reporting enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved reporting and export usability ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Reporting and export improvements and performance updates * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation * Improved product responsiveness across key pages ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Watchlist and monitoring improvements and performance updates * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved product responsiveness across key pages ### Reporting and export improvements * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation ### Performance and reliability improvements and localization updates * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved multilingual experience and terminology consistency ### Threat intelligence experience improvements * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information # Create asset Source: https://docs.defendis.com/api-reference/assets-watchlist/create-asset /openapi.json post /api/v1/watchlists/assets # Delete assets Source: https://docs.defendis.com/api-reference/assets-watchlist/delete-assets /openapi.json post /api/v1/watchlists/assets/delete # List assets Source: https://docs.defendis.com/api-reference/assets-watchlist/list-assets /openapi.json get /api/v1/watchlists/assets # Update asset Source: https://docs.defendis.com/api-reference/assets-watchlist/update-asset /openapi.json put /api/v1/watchlists/assets/{id} # Create BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/create-bin /openapi.json post /api/v1/watchlists/bin Creates a BIN in the current enterprise watchlist. # Delete BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/delete-bins /openapi.json post /api/v1/watchlists/bin/delete # List BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/list-bins /openapi.json get /api/v1/watchlists/bin # Update BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/update-bin /openapi.json put /api/v1/watchlists/bin/{id} # Credentials (domain) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-domain /openapi.json get /api/v1/dataleaks/credentials # Credentials (email) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-email /openapi.json get /api/v1/dataleaks/credentials/email # Dataleaks stats Source: https://docs.defendis.com/api-reference/dataleaks/dataleaks-stats /openapi.json get /api/v1/dataleaks/stats # Documents (domain) Source: https://docs.defendis.com/api-reference/dataleaks/documents-domain /openapi.json get /api/v1/dataleaks/documents # Payment Cards Source: https://docs.defendis.com/api-reference/dataleaks/payment-cards /openapi.json get /api/v1/dataleaks/paymentcards/bins # Victim profile Source: https://docs.defendis.com/api-reference/dataleaks/victim-profile /openapi.json get /api/v1/dataleaks/user # Create domain Source: https://docs.defendis.com/api-reference/domains-watchlist/create-domain /openapi.json post /api/v1/watchlists/domain Creates a domain in the current enterprise watchlist. # Delete domains Source: https://docs.defendis.com/api-reference/domains-watchlist/delete-domains /openapi.json post /api/v1/watchlists/domain/delete # List domains Source: https://docs.defendis.com/api-reference/domains-watchlist/list-domains /openapi.json get /api/v1/watchlists/domain # Update domain Source: https://docs.defendis.com/api-reference/domains-watchlist/update-domain /openapi.json put /api/v1/watchlists/domain/{id} # Create executive Source: https://docs.defendis.com/api-reference/executives-watchlist/create-executive /openapi.json post /api/v1/watchlists/executive # Delete executives Source: https://docs.defendis.com/api-reference/executives-watchlist/delete-executives /openapi.json post /api/v1/watchlists/executive/delete # List executives Source: https://docs.defendis.com/api-reference/executives-watchlist/list-executives /openapi.json get /api/v1/watchlists/executive # Update executive Source: https://docs.defendis.com/api-reference/executives-watchlist/update-executive /openapi.json put /api/v1/watchlists/executive/{id} # CVE details Source: https://docs.defendis.com/api-reference/exposure/cve-details /openapi.json get /api/v1/exposure/cves/{id} # CVEs Source: https://docs.defendis.com/api-reference/exposure/cves /openapi.json get /api/v1/exposure/cves # DNS records Source: https://docs.defendis.com/api-reference/exposure/dns-records /openapi.json get /api/v1/exposure/dns # Hosts Source: https://docs.defendis.com/api-reference/exposure/hosts /openapi.json get /api/v1/exposure/hosts # JavaScript findings Source: https://docs.defendis.com/api-reference/exposure/javascript-findings /openapi.json get /api/v1/exposure/js # Ports Source: https://docs.defendis.com/api-reference/exposure/ports /openapi.json get /api/v1/exposure/ports # Subdomains Source: https://docs.defendis.com/api-reference/exposure/subdomains /openapi.json get /api/v1/exposure/subdomains # Surface vulnerabilities Source: https://docs.defendis.com/api-reference/exposure/surface-vulnerabilities /openapi.json get /api/v1/exposure/vulnerabilities # Health Source: https://docs.defendis.com/api-reference/health/health /openapi.json get /health # Create keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/create-keyword /openapi.json post /api/v1/watchlists/keyword Creates a keyword in the current enterprise watchlist. # Delete keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/delete-keywords /openapi.json post /api/v1/watchlists/keyword/delete # List keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/list-keywords /openapi.json get /api/v1/watchlists/keyword # Update keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/update-keyword /openapi.json put /api/v1/watchlists/keyword/{id} # Create ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/create-ransom-group /openapi.json post /api/v1/watchlists/ransom # Delete ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/delete-ransom-groups /openapi.json post /api/v1/watchlists/ransom/delete # List ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/list-ransom-groups /openapi.json get /api/v1/watchlists/ransom # Update ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/update-ransom-group /openapi.json put /api/v1/watchlists/ransom/{id} # Group details Source: https://docs.defendis.com/api-reference/ransomware/group-details /openapi.json get /api/v1/ransom/groups/{id} # Groups Source: https://docs.defendis.com/api-reference/ransomware/groups /openapi.json get /api/v1/ransom/groups # Ransomware stats Source: https://docs.defendis.com/api-reference/ransomware/ransomware-stats /openapi.json post /api/v1/ransom/stats # Victims Source: https://docs.defendis.com/api-reference/ransomware/victims /openapi.json get /api/v1/ransom/victims # Victims (by country) Source: https://docs.defendis.com/api-reference/ransomware/victims-by-country /openapi.json get /api/v1/ransom/country/victims # Create group Source: https://docs.defendis.com/api-reference/watchlists/create-group /openapi.json post /api/v1/watchlists/create # Delete groups Source: https://docs.defendis.com/api-reference/watchlists/delete-groups /openapi.json post /api/v1/watchlists/delete # Group stats Source: https://docs.defendis.com/api-reference/watchlists/group-stats /openapi.json get /api/v1/watchlists/stats # List groups Source: https://docs.defendis.com/api-reference/watchlists/list-groups /openapi.json get /api/v1/watchlists # Update group Source: https://docs.defendis.com/api-reference/watchlists/update-group /openapi.json put /api/v1/watchlists/{id} # Authentication Source: https://docs.defendis.com/api/auth Defendis API uses bearer API keys for authentication and enterprise scope for authorization. ## API key Send your API key in the `Authorization` header for all customer endpoints under `/api/v1/*`: ```http theme={null} Authorization: Bearer ``` ```bash theme={null} #Example request: curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## API key lifecycle API keys are created and managed in [Defendis web app](https://app.defendis.com). Use unique keys per integration (SIEM, data lake ingestion, SOAR automation). Rotate keys on a schedule (every 60 to 90 days) and immediately after any suspected exposure. Revoke unused keys promptly to reduce your exposure. ## Authorisation scope Each API key is bound to a workspace scope. The API enforces access to workspace-owned resources and input validation for scoped endpoints. Out-of-scope requests will return 403 Forbidden Dataleaks endpoints are intentionally strict to prevent data leakage: * Requests require scoped inputs (`domain`, `email`, or `bin` depending on endpoint). * Missing required scoped parameters return 400 Bad Request. * Out-of-scope inputs return 403 Forbidden.. * Enterprise billing access restrictions may also return 403 Forbidden on protected routes. ## Common failures ```http theme={null} # Missing API key HTTP/1.1 401 Unauthorized { "error": "Missing API key" } ``` ```http theme={null} # Invalid or revoked API key HTTP/1.1 401 Unauthorized { "error": "Invalid or revoked API key" } ``` ## Securing your integration These recommendations cover the minimum security and observability controls we expect for production integrations, including secrets handling, least-privilege access, and request correlation: Store API keys in a secret manager, never in source control or client-side code. Restrict key access to only the workloads that need it. Never log the full Authorization header. Capture `x-request-id` response header to speed up investigations. # Deployment Source: https://docs.defendis.com/api/deployment This page explains how the Defendis API evolves over time: versioning guarantees, compatibility expectations, and the practices you should follow to keep production integrations stable. ## Versioning policy Defendis uses path-based versioning. Current customer API is `/api/v1` ### Backward-compatible changes We may introduce backward-compatible improvements without changing the version, including: Adding new endpoints. Adding new optional query parameters. Adding new fields to existing responses. For forward compatibility, ignore unknown response fields and avoid strict JSON parsing that fails on additional properties. ### Breaking changes Breaking changes will be introduced under a new version prefix `/api/v2`. # endpoints Source: https://docs.defendis.com/api/endpoints This page gives you a practical map of which endpoint families exist, what they’re used for, and how they fit together in a real integration. ## Recommended integration flow Most customer integrations follow this pattern: Use watchlists to define scope (domains, keywords, BINs, executives, assets). Query Dataleaks, Exposure, and Ransomware datasets with scoped inputs. Ingest incrementally using pagination and date windows where supported. Normalize and correlate results into downstream systems such as SIEM, SOAR, a data lake, or case management. ## Response envelope Successful responses use a consistent top-level envelope: ```json title="Single resource" theme={null} { "data": { "...": "..." } } ``` ```json title="List endpoints" theme={null} { "data": [{ "...": "..." }], "paging": { "...": "..." } } ``` ```json title="Batch delete" theme={null} { "data": { "count": 3 } } ``` ## Health Use this for basic connectivity checks (no auth required): ```bash title="Health request" theme={null} curl -sS "https://api.defendis.com/health" ``` ## Watchlists Watchlists are the foundation of authorization scope. * `GET /api/v1/watchlists` * `POST /api/v1/watchlists/create` * `PUT /api/v1/watchlists/{id}` * `POST /api/v1/watchlists/delete` * `GET /api/v1/watchlists/stats` * `GET /api/v1/watchlists/assets` * `POST /api/v1/watchlists/assets` * `PUT /api/v1/watchlists/assets/{id}` * `POST /api/v1/watchlists/assets/delete` * `GET /api/v1/watchlists/domain` * `POST /api/v1/watchlists/domain` * `PUT /api/v1/watchlists/domain/{id}` * `POST /api/v1/watchlists/domain/delete` * `GET /api/v1/watchlists/bin` * `POST /api/v1/watchlists/bin` * `PUT /api/v1/watchlists/bin/{id}` * `POST /api/v1/watchlists/bin/delete` * `GET /api/v1/watchlists/executive` * `POST /api/v1/watchlists/executive` * `PUT /api/v1/watchlists/executive/{id}` * `POST /api/v1/watchlists/executive/delete` * `GET /api/v1/watchlists/keyword` * `POST /api/v1/watchlists/keyword` * `PUT /api/v1/watchlists/keyword/{id}` * `POST /api/v1/watchlists/keyword/delete` * `GET /api/v1/watchlists/ransom` * `POST /api/v1/watchlists/ransom` * `PUT /api/v1/watchlists/ransom/{id}` * `POST /api/v1/watchlists/ransom/delete` Many list endpoints accept an optional `watchlistid` query parameter, and batch-delete endpoints use a JSON request body with an `ids` array. `POST /api/v1/watchlists/domain`, `POST /api/v1/watchlists/keyword`, and `POST /api/v1/watchlists/bin` can return: * `403 Forbidden` when enterprise billing access is denied. * `409 Conflict` when the corresponding workspace quota is reached (`quota_domains_reached`, `quota_keywords_reached`, `quota_bins_reached`). ## Modules * `GET /api/v1/dataleaks/credentials` // requires `domain` * `GET /api/v1/dataleaks/credentials/email` // requires `email` * `GET /api/v1/dataleaks/documents` // requires `domain` * `GET /api/v1/dataleaks/paymentcards/bins` // requires `bin` * `GET /api/v1/dataleaks/stats` // requires `domain` * `GET /api/v1/dataleaks/user` // requires `id` * `GET /api/v1/exposure/cves` * `GET /api/v1/exposure/subdomains` * `GET /api/v1/exposure/hosts` // requires `domainId` * `GET /api/v1/exposure/ports` * `GET /api/v1/exposure/vulnerabilities` Start with `subdomains` and `hosts` to build inventory, then use `ports` and `vulnerabilities` for risk triage and reporting. * `POST /api/v1/ransom/stats` // overview stats and trends * `GET /api/v1/ransom/groups` // actor and group listing * `GET /api/v1/ransom/groups/{id}` // group details * `GET /api/v1/ransom/victims` // victim activity listing * `GET /api/v1/ransom/country/victims` // victim activity by country # Errors Source: https://docs.defendis.com/api/errors Defendis API uses standard HTTP status codes and a JSON error envelope. This page explains how to handle errors safely in production, including which scenarios are retryable. ## Error response format Most error responses use this shape: ```json theme={null} { "error": "string", "message": "string (optional)" } ``` Implementation principles: Treat error as a human-readable reason, not a stable enum. Ignore unknown response fields for forward compatibility. Never log secrets, especially the `Authorization` header. ## Status codes and retry actions | Status code | Meaning | Retry strategy | Recommended action | | ----------------------- | ----------------------------------------------------- | -------------- | ---------------------------------------------------------------- | | `400 Bad Request` | Missing or invalid parameters/JSON body | No | Fix request shape or required inputs | | `401 Unauthorized` | Missing, invalid, or revoked API key | No | Validate credentials and replace/re-enable key | | `403 Forbidden` | Authenticated but blocked by enterprise access policy | No | Verify enterprise scope/eligibility and enterprise billing state | | `409 Conflict` | Workspace quota reached on write operations | No | Reduce usage or increase workspace quotas, then retry | | `404 Not Found` | Unknown endpoint or resource | No | Confirm endpoint path, method, and resource identifiers | | `429 Too Many Requests` | Rate limit exceeded | Yes | Retry with exponential backoff + jitter | | `500/502/503/504` | Transient server-side failure | Conditional | Retry safe requests (`GET`) with backoff | ## Common examples | Scenario | HTTP status | Example error body | | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | Missing API key | `401 Unauthorized` | `{ "error": "Missing API key" }` | | Out-of-scope request | `403 Forbidden` | `{ "error": "You don't have permission to view this" }` | | Enterprise billing access denied | `403 Forbidden` | `{ "error": "Enterprise billing access denied", "reason": "payment_unpaid", "status": "unpaid" }` | | Watchlist quota reached | `409 Conflict` | `{ "error": "quota_domains_reached", "metric": "domains", "used": 10, "limit": 10, "requestedIncrement": 1 }` | | Rate limit exceeded | `429 Too Many Requests` | `{ "error": "Rate limit exceeded" }` | ### Backoff snippet ```js title="JavaScript backoff snippet" theme={null} function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); } async function fetchGetWithBackoff(url, options = {}, { maxRetries = 5, baseDelayMs = 500 } = {}) { const retryableStatuses = new Set([429, 500, 502, 503, 504]); for (let attempt = 0; attempt <= maxRetries; attempt++) { try { const res = await fetch(url, { ...options, method: "GET" }); if (!retryableStatuses.has(res.status)) return res; if (attempt === maxRetries) return res; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } catch (error) { if (attempt === maxRetries) throw error; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } } } ``` ```python title="Python backoff snippet" theme={null} import random import time import requests def get_with_backoff(url, headers, max_retries=5, base_delay_s=0.5, timeout_s=30): retryable_statuses = {429, 500, 502, 503, 504} for attempt in range(max_retries + 1): try: resp = requests.get(url, headers=headers, timeout=timeout_s) except requests.RequestException: if attempt == max_retries: raise resp = None if resp is not None and resp.status_code not in retryable_statuses: return resp if attempt == max_retries: return resp delay = min(30.0, base_delay_s * (2 ** attempt)) jitter = random.uniform(0, 0.25) time.sleep(delay + jitter) ``` ## Troubleshooting checklist When contacting Support, include: Include the request path `example: /api/v1/dataleaks/stats` Include the UTC timestamp and your client request ID. Include the HTTP status code and the error response body. Include the parameters you sent, with sensitive values redacted. # Getting Started Source: https://docs.defendis.com/api/getting-started This guide helps you make your first successful request to the Defendis API and adopt conventions that make your integration reliable in production. ## Quickstart ```http theme={null} curl -sS "https://api.defendis.com/health" ``` ```http theme={null} #Expected response: { "status": "ok" } ``` ```bash theme={null} export DEFENDIS_API_KEY="YOUR_API_KEY" ``` ```bash theme={null} curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## Core concepts ### Watchlists Datasets in Defendis are access-controlled by your workspace scope. In practice: * You define watchlists that represent what you are authorised to monitor (`domains`, `emails`, `keywords`, `BINs`, and other assets). * Many endpoints validate input against your watchlist scope. * Requests outside your approved scope return 403 Forbidden. * Watchlist write endpoints may return 409 Conflict when your workspace quota is reached. ### Contract-first integration * The OpenAPI spec is the source of truth for endpoints, parameters, and request/response schemas: `../openapi.yaml`. * If you generate clients, treat the API as additive: new fields may appear without warning. Your parser should ignore unknown fields. ## Request conventions ### Content types * Use query parameters for filtering and pagination on endpoints that support them. * When an endpoint accepts a request body, send JSON: ```http theme={null} Content-Type: application/json ``` For more information, see [Errors](/api/errors) and [Endpoints](/api/endpoints). ### Pagination Paginated list endpoints return a consistent envelope: * `data`: array of records * `paging`: pagination metadata with: * `currentPage` * `pageSize` * `totalRecords` * `totalPages` * `hasMore` * `nextPage` Recommended ingestion loop: * Start with `page=1`. * Keep fetching until `paging.hasMore` is `false` (or `paging.nextPage` is `null`). * Persist checkpoints (page and filter window) so your ingestion can resume safely after failures. ```json title="Example" theme={null} { "data": [], "paging": { "currentPage": 1, "pageSize": 50, "totalRecords": 120, "totalPages": 3, "hasMore": true, "nextPage": 2 } } ``` ### Date filters Some endpoints support date window filtering. When supported, use a closed-open window: * `fromDate`: inclusive lower bound * `toDate`: exclusive upper bound Date parameters are standardized as `fromDate` and `toDate`. Always follow the endpoint’s reference docs / OpenAPI contract for exact support. Client recommendation: * Use `YYYY-MM-DD` for date-only filters. * Prefer narrow windows for high-volume pulls and widen gradually. ### Search & sorting Search and sorting are endpoint-specific. Common patterns include: * `search` * `sortBy` * `sortOrder` When omitted, server-side defaults apply. Use the OpenAPI contract and the endpoint reference docs to confirm supported parameters and allowed values. ## Rate limits & reliability Defendis enforces rate limiting. When exceeded you will receive 429 Too Many Requests. Client best practices: * Use exponential backoff for retries (with jitter). * Distribute polling workloads over time. * Automatically retry **safe** requests (GET) on transient failures (`429`, `5xx`, timeouts). * Avoid retrying non-idempotent writes unless your application guarantees idempotency. ## Typical integration patterns ### Pull model Configure watchlists so your integration only pulls data within approved scope. Ingest Dataleaks, Exposure, and Ransomware datasets on a recurring schedule. Map results into your SIEM/SOAR, data lake, or case management schema. ### Near-real-time workflows For operational workflows, use frequent polling with small time windows and robust retry/backoff behavior. ## Data handling & privacy Some datasets, especially `Dataleaks`, may contain sensitive information. As an API consumer, you are responsible for ensuring the data is handled appropriately within your environment. Recommended practices: Keep only the fields and retention window required for your workflow. Limit sensitive dataset access to the smallest set of users and services. Avoid logging full payloads or sensitive fields in application and audit logs. Apply your internal security, legal, and compliance controls to this API data. # Introduction Source: https://docs.defendis.com/api/index Defendis API lets you integrate external threat signals into your product and security workflows to automate monitoring and enrichment. Use this API to: Query data leak signals for approved identifiers (domains, BINs, etc). Create and manage watchlists that define what you monitor. Analyse your external exposure and track ransomware activity. ## Base URL and versioning * Base URL: `https://api.defendis.com` * Version prefix: `/api/v1` Example endpoint: `https://api.defendis.com/api/v1/watchlists` ## Authentication All `/api/v1/*` endpoints require an API key: ```http theme={null} Authorization: Bearer ``` ## Start here Make your first request and learn integration patterns. API keys, authorization scope, and security best practices. Guidance on which endpoint family to use, with OpenAPI reference. Error model, retry behavior, and troubleshooting. Availability, versioning policy, and change management. ## Downloads * Download the `Postman file` * Import the OpenAPI spec URL: `https://api.defendis.com/openapi.json` # Changelog Source: https://docs.defendis.com/changelog ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Navigation and usability improvements and integration enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved API integration access and configuration flows ### Navigation and usability improvements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks ### Navigation and usability improvements and alerting enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved reliability of notifications and alerts ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Integration access and developer experience improvements and security enhancements * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding * More reliable behavior for enterprise integration scenarios * Strengthened account access and verification flows ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Service‑Provider Billing & Workspace Improvements * Introduced service‑provider‑managed billing for more flexible workspace payments * Enhanced billing breakdowns for clearer cost visibility * Improved signup and verification flow for a smoother onboarding experience * Fixed minor issues and refreshed documentation pages for better clarity ### Improved Billing * Enhanced billing management * General refinements for better reliability and maintainability ### Enhanced Billing, Security, and Workspace Controls * *Stronger account security:* Refined MFA and session handling to ensure smoother, more reliable authentication * Strengthened account access and verification flows ### Improved Access and reliability * Enhanced subscription permission checks for smoother access * Improved overall product stability and reliability ### Improved Trial License and Billing Display * Clearer display of billing amounts for all license types * Enhanced handling of trial licenses for a smoother experience * More accurate and transparent billing information throughout the app * Improved overall product stability and reliability ### Improved Reliability for Authentication Requests * Extended retry window for temporary authentication issues to reduce login interruptions * Enhances overall stability when network conditions are inconsistent * Provides a smoother sign-in experience with fewer transient errors * Improved overall product stability and reliability ### Improved Session Stability and Refresh Handling * Enhanced session handling ensures smoother reconnections and fewer interruptions * Provides a more reliable and consistent experience when working across multiple sessions * Strengthened account access and verification flows ### Improved Stability and Minor Enhancements * Enhanced overall app stability for a smoother experience * Fixed minor issues to improve reliability and performance * Optimized background processes for faster response times * Improved overall product stability and reliability ### Improved Billing, Authentication, and Subscription Experience * Smarter billing: Introduces catalog-based billing with flexible, document-level discounts * Smoother sign-in: Enhanced authentication retry flow and refined interface for better usability * Faster loading: Updated loading visuals and automatic fallback for terminal licenses ### Improved Billing and Access Experience * Enhanced billing workflows for greater accuracy and reliability * Streamlined access controls to ensure smoother user management * Minor performance and stability improvements across the platform * Improved API integration access and configuration flows ### Improved Deployment Security and Performance * Enhanced deployment process with secure Google Cloud integration * Improved reliability through updated service account management * Improved reliability of notifications and alerts * Better clarity when tracking important updates ### Improved Security, Streaming, and Workspace Controls * Enhanced session management with new logout options and smoother refresh handling * Strengthened workspace access controls with billing fallback for uninterrupted service * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced Member Notifications in Console * Introduces a new notifications feature for console members * Enables real-time updates and alerts directly within the console * Improves visibility and responsiveness for team activities * Delivers a smoother, more connected user experience ### Improved Billing, Permissions, and Workspace Management * Enhanced billing experience with new payment form states and improved Stripe integration * Added permission catalog service for more flexible access control * Improved workspace management with safer deletion and new catalog features * Improved API integration access and configuration flows ### Improved Workspace Experience * Introduced enhanced workspace management with clearer allocation and usage controls * Improved user and billing management capabilities for workspace administrators * Improved navigation and overall usability ### Improved Workspace Management and Onboarding * Introduced user verification and guided onboarding sessions for a smoother start * Enhanced invite acceptance and redirect flow for a more seamless joining experience * Improved session reliability and visual alignment in the header ### Improved Data Security and Billing Reliability * General stability and performance enhancements for smoother operations * Improved overall product stability and reliability * Enhanced usability across key product areas ### Improved Workspace Billing Sync * Reduces potential discrepancies in billing information * Provides a smoother experience when managing workspace billing changes * Improved navigation and overall usability ### Improved Search Efficiency and Workspace Access Alignment * Search updates are now faster and more responsive, reducing unnecessary refreshes * Overall experience is smoother with improved performance and reliability * Improved product responsiveness across key pages ### Improved Workspace Insights and Session Reliability * Enjoy smoother session experiences with enhanced refresh handling * Improved reliability and control for workspace management tasks * Improved API integration access and configuration flows ### Performance and Stability Improvements * Enhanced overall app responsiveness for a smoother experience * Improved reliability to reduce unexpected errors * Minor interface refinements for better usability * General maintenance updates to keep things running efficiently ### Workspace Stability Improvements * Improved handling of approved workspace differences to reduce unnecessary alerts * General stability and performance enhancements for smoother workspace operations * Improved navigation and overall usability ### Improved Enterprise Billing Accuracy and Data Access * Improved data retrieval for faster and more reliable billing information * Streamlined reconciliation process to reduce potential discrepancies * Improved overall product stability and reliability ### Improved Billing Options and License Sync * Added support for a **Free** billing status to simplify account management * Workspaces now automatically **synchronize license details**, ensuring accurate and up‑to‑date access * Enhancements improve transparency and reduce manual updates for workspace admins * Improved navigation and overall usability ### Improved Workspace Licensing and Error Handling * Introduced enhanced workspace licensing with updated data models * Improved reliability through better error handling and duplicate prevention * Streamlined membership updates to maintain consistency and accuracy * Refreshed documentation pages for clearer guidance ### Improved Reports * Generate reports with your enterprise avatar and default logo for a more personalized look * Analytics now automatically adapts to your region for more accurate insights * Improved export usability ### Improved reliability for notification counts * Notification counts now update more consistently, even in unstable network conditions * Enhanced error handling ensures smoother user experience when fetching notifications * Overall reliability and responsiveness of notifications have been improved ### Enhanced Authentication * Improved sign-in reliability with updated authentication flow * Provides a smoother and more secure reauthentication experience for users * Strengthened account access and verification flows ### Improved API and Watchlist Management * Added enterprise ID support to API calls for better integration and control * Enhanced watchlist domain management for more accurate tracking * Improved CVE asset matching to strengthen vulnerability insights * Improved API integration access and configuration flows ### Improved app stability, CVE Tools, and Ransomware Insights * Enhanced authentication, Improved performance, and clearer error feedback * Added ransomware victim summaries, detailed views, and country-based filtering for deeper insights * Strengthened account access and verification flows ### Improved Error Handling and Watchlist Enhancements * Enhanced watchlist functionality with enterprise-grade validation * Improved overall stability and consistency across the platform * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Improved performance and simplified app behavior * Streamlined app configuration for faster load times * Reduced unnecessary redirects to improve navigation * Enhanced reliability and consistency across user sessions * Improved navigation and overall usability ### Improved Authentication and Session Reliability * Added automatic redirection to help users recover sessions after cutover events * Enhanced session handling for smoother, more reliable sign-ins * Improved overall stability and continuity during authentication transitions * Strengthened account access and verification flows ### Improved Resource Management with Custom Cache Controls * Enhanced performance through smarter caching behavior * Faster load times and reduced redundant data requests * More consistent user experience when accessing stored resources * Improved navigation and overall usability ### Improved API performance and reliability * Enhanced API responsiveness with smarter rate limiting for task updates * Improved connection stability to ensure smoother, more consistent interactions * Delivers a faster and more reliable experience for high-volume API users * Improved API integration access and configuration flows ### Improved Task Status Tracking and Batch Updates * Enjoy more accurate and consistent task progress updates * Benefit from smoother monitoring of large-scale task operations * Improved API integration access and configuration flows ### Improved Enterprise Update Experience * Enhanced enterprise update process for smoother data management * General usability improvements for a faster, more reliable experience * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Improved Support Experience and Settings Enhancements * Introduced a new Support Overview for easier access to key support information * Enhanced Support Settings with clearer labels and a more intuitive layout * Streamlined navigation to help users manage support preferences more efficiently * Improved API integration access and configuration flows ### Improved Billing and watchlist management * Past due accounts are now subject to a 7 days grace period * More accurate scope validation and smoother loading states in your watchlist dropdown * Faster, more reliable interactions across tasks management * Improved API integration access and configuration flows ### Improved Chat User Identity and Settings * Enhanced Chat integration for more accurate user identification * Simplified configuration options for managing communication settings * Improved reliability and consistency in user messaging experiences * Strengthened account access and verification flows ### Improved Task Management and Session Handling * Enhanced task management experience with improved UI and selection tools * Improved session and authentication handling for more reliable logins and logouts ### Improved Dashboard Stability and Error Handling * Enhanced reliability of dashboard statistics display * Improved handling of unexpected data or connection issues * Reduced likelihood of dashboard errors impacting user experience * Improved reporting and export usability ### Improved Session Reliability and Fraud Detection * Enhanced session management for more reliable and secure user experiences * Updated billing documentation for clearer incident response guidance * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages ### Improved Fraud Detail Loading Performance * Faster loading times when viewing fraud details * Smoother experience when switching between fraud cases * Enhanced reliability and consistency in fraud data display * Improved product responsiveness across key pages ### Enhanced Fraud Management and Navigation * Updates fraud tabs and localization for a clearer, more consistent interface * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages * Better readability in user-facing content ### Improved Subscription Stability and Error Handling * Enhanced reliability when managing enterprise subscriptions * Reduced likelihood of subscription errors and interruptions * Improved clarity of error messages for smoother user experience * Improved overall product stability and reliability ### Improved Host Node Display in Surface Maps * Host node visuals now render with consistent width for better clarity * Enhanced readability and alignment across different map views * Minor stability improvements for smoother map interactions * Improved overall product stability and reliability ### Enhanced Feed, Intelligence, and Map Experiences * Introduced a new integrated feed experience with improved performance and real-time updates * Expanded intelligence features with enhanced loading states and new airport country insights * Refreshed map visuals and improved key management for smoother navigation * Added richer surface map details, including DNS summaries and clearer host information ### Easily Delete Workspaces * Added the ability to permanently delete workspaces when no longer needed * Simplifies workspace management and keeps your environment organized * Ensures a smoother experience when cleaning up unused projects * Improved navigation and overall usability ### Integration access and developer experience improvements * Improved API integration to support more reliable connections * Increased overall stability and performance for development operations * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced APIs, Subscriptions, and Surface Map * Introduced API subscriptions for easier integration and management * Added Surface Map API with improved navigation for better visibility * Expanded surface and vulnerability APIs with watchlist support * Improved scan time display and overall interface consistency ### Improved Navigation and Enterprise Search Enhancements * Enhanced header with refined enterprise search and clearer billing filters * Streamlined enterprise switching for smoother account transitions * Added new indicators and brand menu for better visibility and control * General performance and stability improvements across the platform ### Improved Enterprise Switching and Reliability * Enhanced enterprise account switching for a smoother experience * Improved error handling to reduce interruptions and ensure stability * Minor performance refinements for faster, more reliable workflows * Improved overall product stability and reliability ### Backend improvements * Added new billing filters for easier account management * Refined subscription handling for smoother plan updates * Improved date range formatting and clearer subscription type labels ### Improved Billing, Security, and Developer Experience * **Simplified billing management:** New tools and clearer UI for managing billing, quotas, and access * **Enhanced security settings:** Updated interface and improved user experience * **Better developer tools:** Updated API documentation for smoother integrations ### Developer Mode release with usability and export improvements * Released Developer Mode for advanced security exploration workflows * Improved navigation and overall usability across key product areas * Smoother interactions in frequently used screens * Improved reporting and export usability ### Enterprise API setup improvements * Improved enterprise ID handling in API integration settings * More reliable request behavior during integration setup * Smoother configuration experience for API administrators ### Watchlist and monitoring improvements and reporting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reporting and export usability ### API docs and access reliability improvements * Improved availability of API reference artifacts for integrators * Better consistency when loading integration resources * Smoother developer experience during API implementation ### Expanded API integration coverage * Improved API documentation coverage for integration use cases * Easier access to integration resources for implementation teams * Better clarity when validating supported integration paths ### Integration stability improvements * Improved reliability for API integration traffic handling * Better diagnostics support for troubleshooting integration issues * Smoother overall experience for connected applications ### Integration security and access improvements * Improved cross-origin access controls for safer integrations * Better protection for API integrations used across environments * More consistent behavior for authenticated integration requests ### Account security improvements and monitoring enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved watchlist management and indicator handling ### Performance and reliability improvements and security enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Strengthened account access and verification flows ### Threat intelligence experience improvements and performance updates * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information * Improved product responsiveness across key pages ### Watchlist and monitoring improvements and intelligence enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved threat intelligence views and data clarity ### Watchlist and monitoring improvements and security enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Strengthened account access and verification flows ### Performance and reliability improvements and alerting enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved reliability of notifications and alerts ### Notification and alerting improvements * Improved reliability of notifications and alerts * Better clarity when tracking important updates * More consistent alert behavior across product areas ### Account security improvements and reporting enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved reporting and export usability ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Reporting and export improvements and performance updates * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation * Improved product responsiveness across key pages ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Watchlist and monitoring improvements and performance updates * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved product responsiveness across key pages ### Reporting and export improvements * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation ### Performance and reliability improvements and localization updates * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved multilingual experience and terminology consistency ### Threat intelligence experience improvements * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information # Create asset Source: https://docs.defendis.com/api-reference/assets-watchlist/create-asset /openapi.json post /api/v1/watchlists/assets # Delete assets Source: https://docs.defendis.com/api-reference/assets-watchlist/delete-assets /openapi.json post /api/v1/watchlists/assets/delete # List assets Source: https://docs.defendis.com/api-reference/assets-watchlist/list-assets /openapi.json get /api/v1/watchlists/assets # Update asset Source: https://docs.defendis.com/api-reference/assets-watchlist/update-asset /openapi.json put /api/v1/watchlists/assets/{id} # Create BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/create-bin /openapi.json post /api/v1/watchlists/bin Creates a BIN in the current enterprise watchlist. # Delete BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/delete-bins /openapi.json post /api/v1/watchlists/bin/delete # List BINs Source: https://docs.defendis.com/api-reference/bins-watchlist/list-bins /openapi.json get /api/v1/watchlists/bin # Update BIN Source: https://docs.defendis.com/api-reference/bins-watchlist/update-bin /openapi.json put /api/v1/watchlists/bin/{id} # Credentials (domain) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-domain /openapi.json get /api/v1/dataleaks/credentials # Credentials (email) Source: https://docs.defendis.com/api-reference/dataleaks/credentials-email /openapi.json get /api/v1/dataleaks/credentials/email # Dataleaks stats Source: https://docs.defendis.com/api-reference/dataleaks/dataleaks-stats /openapi.json get /api/v1/dataleaks/stats # Documents (domain) Source: https://docs.defendis.com/api-reference/dataleaks/documents-domain /openapi.json get /api/v1/dataleaks/documents # Payment Cards Source: https://docs.defendis.com/api-reference/dataleaks/payment-cards /openapi.json get /api/v1/dataleaks/paymentcards/bins # Victim profile Source: https://docs.defendis.com/api-reference/dataleaks/victim-profile /openapi.json get /api/v1/dataleaks/user # Create domain Source: https://docs.defendis.com/api-reference/domains-watchlist/create-domain /openapi.json post /api/v1/watchlists/domain Creates a domain in the current enterprise watchlist. # Delete domains Source: https://docs.defendis.com/api-reference/domains-watchlist/delete-domains /openapi.json post /api/v1/watchlists/domain/delete # List domains Source: https://docs.defendis.com/api-reference/domains-watchlist/list-domains /openapi.json get /api/v1/watchlists/domain # Update domain Source: https://docs.defendis.com/api-reference/domains-watchlist/update-domain /openapi.json put /api/v1/watchlists/domain/{id} # Create executive Source: https://docs.defendis.com/api-reference/executives-watchlist/create-executive /openapi.json post /api/v1/watchlists/executive # Delete executives Source: https://docs.defendis.com/api-reference/executives-watchlist/delete-executives /openapi.json post /api/v1/watchlists/executive/delete # List executives Source: https://docs.defendis.com/api-reference/executives-watchlist/list-executives /openapi.json get /api/v1/watchlists/executive # Update executive Source: https://docs.defendis.com/api-reference/executives-watchlist/update-executive /openapi.json put /api/v1/watchlists/executive/{id} # CVE details Source: https://docs.defendis.com/api-reference/exposure/cve-details /openapi.json get /api/v1/exposure/cves/{id} # CVEs Source: https://docs.defendis.com/api-reference/exposure/cves /openapi.json get /api/v1/exposure/cves # DNS records Source: https://docs.defendis.com/api-reference/exposure/dns-records /openapi.json get /api/v1/exposure/dns # Hosts Source: https://docs.defendis.com/api-reference/exposure/hosts /openapi.json get /api/v1/exposure/hosts # JavaScript findings Source: https://docs.defendis.com/api-reference/exposure/javascript-findings /openapi.json get /api/v1/exposure/js # Ports Source: https://docs.defendis.com/api-reference/exposure/ports /openapi.json get /api/v1/exposure/ports # Subdomains Source: https://docs.defendis.com/api-reference/exposure/subdomains /openapi.json get /api/v1/exposure/subdomains # Surface vulnerabilities Source: https://docs.defendis.com/api-reference/exposure/surface-vulnerabilities /openapi.json get /api/v1/exposure/vulnerabilities # Health Source: https://docs.defendis.com/api-reference/health/health /openapi.json get /health # Create keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/create-keyword /openapi.json post /api/v1/watchlists/keyword Creates a keyword in the current enterprise watchlist. # Delete keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/delete-keywords /openapi.json post /api/v1/watchlists/keyword/delete # List keywords Source: https://docs.defendis.com/api-reference/keywords-watchlist/list-keywords /openapi.json get /api/v1/watchlists/keyword # Update keyword Source: https://docs.defendis.com/api-reference/keywords-watchlist/update-keyword /openapi.json put /api/v1/watchlists/keyword/{id} # Create ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/create-ransom-group /openapi.json post /api/v1/watchlists/ransom # Delete ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/delete-ransom-groups /openapi.json post /api/v1/watchlists/ransom/delete # List ransom groups Source: https://docs.defendis.com/api-reference/ransom-watchlist/list-ransom-groups /openapi.json get /api/v1/watchlists/ransom # Update ransom group Source: https://docs.defendis.com/api-reference/ransom-watchlist/update-ransom-group /openapi.json put /api/v1/watchlists/ransom/{id} # Group details Source: https://docs.defendis.com/api-reference/ransomware/group-details /openapi.json get /api/v1/ransom/groups/{id} # Groups Source: https://docs.defendis.com/api-reference/ransomware/groups /openapi.json get /api/v1/ransom/groups # Ransomware stats Source: https://docs.defendis.com/api-reference/ransomware/ransomware-stats /openapi.json post /api/v1/ransom/stats # Victims Source: https://docs.defendis.com/api-reference/ransomware/victims /openapi.json get /api/v1/ransom/victims # Victims (by country) Source: https://docs.defendis.com/api-reference/ransomware/victims-by-country /openapi.json get /api/v1/ransom/country/victims # Create group Source: https://docs.defendis.com/api-reference/watchlists/create-group /openapi.json post /api/v1/watchlists/create # Delete groups Source: https://docs.defendis.com/api-reference/watchlists/delete-groups /openapi.json post /api/v1/watchlists/delete # Group stats Source: https://docs.defendis.com/api-reference/watchlists/group-stats /openapi.json get /api/v1/watchlists/stats # List groups Source: https://docs.defendis.com/api-reference/watchlists/list-groups /openapi.json get /api/v1/watchlists # Update group Source: https://docs.defendis.com/api-reference/watchlists/update-group /openapi.json put /api/v1/watchlists/{id} # Authentication Source: https://docs.defendis.com/api/auth Defendis API uses bearer API keys for authentication and enterprise scope for authorization. ## API key Send your API key in the `Authorization` header for all customer endpoints under `/api/v1/*`: ```http theme={null} Authorization: Bearer ``` ```bash theme={null} #Example request: curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## API key lifecycle API keys are created and managed in [Defendis web app](https://app.defendis.com). Use unique keys per integration (SIEM, data lake ingestion, SOAR automation). Rotate keys on a schedule (every 60 to 90 days) and immediately after any suspected exposure. Revoke unused keys promptly to reduce your exposure. ## Authorisation scope Each API key is bound to a workspace scope. The API enforces access to workspace-owned resources and input validation for scoped endpoints. Out-of-scope requests will return 403 Forbidden Dataleaks endpoints are intentionally strict to prevent data leakage: * Requests require scoped inputs (`domain`, `email`, or `bin` depending on endpoint). * Missing required scoped parameters return 400 Bad Request. * Out-of-scope inputs return 403 Forbidden.. * Enterprise billing access restrictions may also return 403 Forbidden on protected routes. ## Common failures ```http theme={null} # Missing API key HTTP/1.1 401 Unauthorized { "error": "Missing API key" } ``` ```http theme={null} # Invalid or revoked API key HTTP/1.1 401 Unauthorized { "error": "Invalid or revoked API key" } ``` ## Securing your integration These recommendations cover the minimum security and observability controls we expect for production integrations, including secrets handling, least-privilege access, and request correlation: Store API keys in a secret manager, never in source control or client-side code. Restrict key access to only the workloads that need it. Never log the full Authorization header. Capture `x-request-id` response header to speed up investigations. # Deployment Source: https://docs.defendis.com/api/deployment This page explains how the Defendis API evolves over time: versioning guarantees, compatibility expectations, and the practices you should follow to keep production integrations stable. ## Versioning policy Defendis uses path-based versioning. Current customer API is `/api/v1` ### Backward-compatible changes We may introduce backward-compatible improvements without changing the version, including: Adding new endpoints. Adding new optional query parameters. Adding new fields to existing responses. For forward compatibility, ignore unknown response fields and avoid strict JSON parsing that fails on additional properties. ### Breaking changes Breaking changes will be introduced under a new version prefix `/api/v2`. # endpoints Source: https://docs.defendis.com/api/endpoints This page gives you a practical map of which endpoint families exist, what they’re used for, and how they fit together in a real integration. ## Recommended integration flow Most customer integrations follow this pattern: Use watchlists to define scope (domains, keywords, BINs, executives, assets). Query Dataleaks, Exposure, and Ransomware datasets with scoped inputs. Ingest incrementally using pagination and date windows where supported. Normalize and correlate results into downstream systems such as SIEM, SOAR, a data lake, or case management. ## Response envelope Successful responses use a consistent top-level envelope: ```json title="Single resource" theme={null} { "data": { "...": "..." } } ``` ```json title="List endpoints" theme={null} { "data": [{ "...": "..." }], "paging": { "...": "..." } } ``` ```json title="Batch delete" theme={null} { "data": { "count": 3 } } ``` ## Health Use this for basic connectivity checks (no auth required): ```bash title="Health request" theme={null} curl -sS "https://api.defendis.com/health" ``` ## Watchlists Watchlists are the foundation of authorization scope. * `GET /api/v1/watchlists` * `POST /api/v1/watchlists/create` * `PUT /api/v1/watchlists/{id}` * `POST /api/v1/watchlists/delete` * `GET /api/v1/watchlists/stats` * `GET /api/v1/watchlists/assets` * `POST /api/v1/watchlists/assets` * `PUT /api/v1/watchlists/assets/{id}` * `POST /api/v1/watchlists/assets/delete` * `GET /api/v1/watchlists/domain` * `POST /api/v1/watchlists/domain` * `PUT /api/v1/watchlists/domain/{id}` * `POST /api/v1/watchlists/domain/delete` * `GET /api/v1/watchlists/bin` * `POST /api/v1/watchlists/bin` * `PUT /api/v1/watchlists/bin/{id}` * `POST /api/v1/watchlists/bin/delete` * `GET /api/v1/watchlists/executive` * `POST /api/v1/watchlists/executive` * `PUT /api/v1/watchlists/executive/{id}` * `POST /api/v1/watchlists/executive/delete` * `GET /api/v1/watchlists/keyword` * `POST /api/v1/watchlists/keyword` * `PUT /api/v1/watchlists/keyword/{id}` * `POST /api/v1/watchlists/keyword/delete` * `GET /api/v1/watchlists/ransom` * `POST /api/v1/watchlists/ransom` * `PUT /api/v1/watchlists/ransom/{id}` * `POST /api/v1/watchlists/ransom/delete` Many list endpoints accept an optional `watchlistid` query parameter, and batch-delete endpoints use a JSON request body with an `ids` array. `POST /api/v1/watchlists/domain`, `POST /api/v1/watchlists/keyword`, and `POST /api/v1/watchlists/bin` can return: * `403 Forbidden` when enterprise billing access is denied. * `409 Conflict` when the corresponding workspace quota is reached (`quota_domains_reached`, `quota_keywords_reached`, `quota_bins_reached`). ## Modules * `GET /api/v1/dataleaks/credentials` // requires `domain` * `GET /api/v1/dataleaks/credentials/email` // requires `email` * `GET /api/v1/dataleaks/documents` // requires `domain` * `GET /api/v1/dataleaks/paymentcards/bins` // requires `bin` * `GET /api/v1/dataleaks/stats` // requires `domain` * `GET /api/v1/dataleaks/user` // requires `id` * `GET /api/v1/exposure/cves` * `GET /api/v1/exposure/subdomains` * `GET /api/v1/exposure/hosts` // requires `domainId` * `GET /api/v1/exposure/ports` * `GET /api/v1/exposure/vulnerabilities` Start with `subdomains` and `hosts` to build inventory, then use `ports` and `vulnerabilities` for risk triage and reporting. * `POST /api/v1/ransom/stats` // overview stats and trends * `GET /api/v1/ransom/groups` // actor and group listing * `GET /api/v1/ransom/groups/{id}` // group details * `GET /api/v1/ransom/victims` // victim activity listing * `GET /api/v1/ransom/country/victims` // victim activity by country # Errors Source: https://docs.defendis.com/api/errors Defendis API uses standard HTTP status codes and a JSON error envelope. This page explains how to handle errors safely in production, including which scenarios are retryable. ## Error response format Most error responses use this shape: ```json theme={null} { "error": "string", "message": "string (optional)" } ``` Implementation principles: Treat error as a human-readable reason, not a stable enum. Ignore unknown response fields for forward compatibility. Never log secrets, especially the `Authorization` header. ## Status codes and retry actions | Status code | Meaning | Retry strategy | Recommended action | | ----------------------- | ----------------------------------------------------- | -------------- | ---------------------------------------------------------------- | | `400 Bad Request` | Missing or invalid parameters/JSON body | No | Fix request shape or required inputs | | `401 Unauthorized` | Missing, invalid, or revoked API key | No | Validate credentials and replace/re-enable key | | `403 Forbidden` | Authenticated but blocked by enterprise access policy | No | Verify enterprise scope/eligibility and enterprise billing state | | `409 Conflict` | Workspace quota reached on write operations | No | Reduce usage or increase workspace quotas, then retry | | `404 Not Found` | Unknown endpoint or resource | No | Confirm endpoint path, method, and resource identifiers | | `429 Too Many Requests` | Rate limit exceeded | Yes | Retry with exponential backoff + jitter | | `500/502/503/504` | Transient server-side failure | Conditional | Retry safe requests (`GET`) with backoff | ## Common examples | Scenario | HTTP status | Example error body | | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | Missing API key | `401 Unauthorized` | `{ "error": "Missing API key" }` | | Out-of-scope request | `403 Forbidden` | `{ "error": "You don't have permission to view this" }` | | Enterprise billing access denied | `403 Forbidden` | `{ "error": "Enterprise billing access denied", "reason": "payment_unpaid", "status": "unpaid" }` | | Watchlist quota reached | `409 Conflict` | `{ "error": "quota_domains_reached", "metric": "domains", "used": 10, "limit": 10, "requestedIncrement": 1 }` | | Rate limit exceeded | `429 Too Many Requests` | `{ "error": "Rate limit exceeded" }` | ### Backoff snippet ```js title="JavaScript backoff snippet" theme={null} function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); } async function fetchGetWithBackoff(url, options = {}, { maxRetries = 5, baseDelayMs = 500 } = {}) { const retryableStatuses = new Set([429, 500, 502, 503, 504]); for (let attempt = 0; attempt <= maxRetries; attempt++) { try { const res = await fetch(url, { ...options, method: "GET" }); if (!retryableStatuses.has(res.status)) return res; if (attempt === maxRetries) return res; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } catch (error) { if (attempt === maxRetries) throw error; const delay = Math.min(30_000, baseDelayMs * 2 ** attempt); const jitter = Math.floor(Math.random() * 250); await sleep(delay + jitter); } } } ``` ```python title="Python backoff snippet" theme={null} import random import time import requests def get_with_backoff(url, headers, max_retries=5, base_delay_s=0.5, timeout_s=30): retryable_statuses = {429, 500, 502, 503, 504} for attempt in range(max_retries + 1): try: resp = requests.get(url, headers=headers, timeout=timeout_s) except requests.RequestException: if attempt == max_retries: raise resp = None if resp is not None and resp.status_code not in retryable_statuses: return resp if attempt == max_retries: return resp delay = min(30.0, base_delay_s * (2 ** attempt)) jitter = random.uniform(0, 0.25) time.sleep(delay + jitter) ``` ## Troubleshooting checklist When contacting Support, include: Include the request path `example: /api/v1/dataleaks/stats` Include the UTC timestamp and your client request ID. Include the HTTP status code and the error response body. Include the parameters you sent, with sensitive values redacted. # Getting Started Source: https://docs.defendis.com/api/getting-started This guide helps you make your first successful request to the Defendis API and adopt conventions that make your integration reliable in production. ## Quickstart ```http theme={null} curl -sS "https://api.defendis.com/health" ``` ```http theme={null} #Expected response: { "status": "ok" } ``` ```bash theme={null} export DEFENDIS_API_KEY="YOUR_API_KEY" ``` ```bash theme={null} curl -sS \ -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \ "https://api.defendis.com/api/v1/watchlists" ``` ## Core concepts ### Watchlists Datasets in Defendis are access-controlled by your workspace scope. In practice: * You define watchlists that represent what you are authorised to monitor (`domains`, `emails`, `keywords`, `BINs`, and other assets). * Many endpoints validate input against your watchlist scope. * Requests outside your approved scope return 403 Forbidden. * Watchlist write endpoints may return 409 Conflict when your workspace quota is reached. ### Contract-first integration * The OpenAPI spec is the source of truth for endpoints, parameters, and request/response schemas: `../openapi.yaml`. * If you generate clients, treat the API as additive: new fields may appear without warning. Your parser should ignore unknown fields. ## Request conventions ### Content types * Use query parameters for filtering and pagination on endpoints that support them. * When an endpoint accepts a request body, send JSON: ```http theme={null} Content-Type: application/json ``` For more information, see [Errors](/api/errors) and [Endpoints](/api/endpoints). ### Pagination Paginated list endpoints return a consistent envelope: * `data`: array of records * `paging`: pagination metadata with: * `currentPage` * `pageSize` * `totalRecords` * `totalPages` * `hasMore` * `nextPage` Recommended ingestion loop: * Start with `page=1`. * Keep fetching until `paging.hasMore` is `false` (or `paging.nextPage` is `null`). * Persist checkpoints (page and filter window) so your ingestion can resume safely after failures. ```json title="Example" theme={null} { "data": [], "paging": { "currentPage": 1, "pageSize": 50, "totalRecords": 120, "totalPages": 3, "hasMore": true, "nextPage": 2 } } ``` ### Date filters Some endpoints support date window filtering. When supported, use a closed-open window: * `fromDate`: inclusive lower bound * `toDate`: exclusive upper bound Date parameters are standardized as `fromDate` and `toDate`. Always follow the endpoint’s reference docs / OpenAPI contract for exact support. Client recommendation: * Use `YYYY-MM-DD` for date-only filters. * Prefer narrow windows for high-volume pulls and widen gradually. ### Search & sorting Search and sorting are endpoint-specific. Common patterns include: * `search` * `sortBy` * `sortOrder` When omitted, server-side defaults apply. Use the OpenAPI contract and the endpoint reference docs to confirm supported parameters and allowed values. ## Rate limits & reliability Defendis enforces rate limiting. When exceeded you will receive 429 Too Many Requests. Client best practices: * Use exponential backoff for retries (with jitter). * Distribute polling workloads over time. * Automatically retry **safe** requests (GET) on transient failures (`429`, `5xx`, timeouts). * Avoid retrying non-idempotent writes unless your application guarantees idempotency. ## Typical integration patterns ### Pull model Configure watchlists so your integration only pulls data within approved scope. Ingest Dataleaks, Exposure, and Ransomware datasets on a recurring schedule. Map results into your SIEM/SOAR, data lake, or case management schema. ### Near-real-time workflows For operational workflows, use frequent polling with small time windows and robust retry/backoff behavior. ## Data handling & privacy Some datasets, especially `Dataleaks`, may contain sensitive information. As an API consumer, you are responsible for ensuring the data is handled appropriately within your environment. Recommended practices: Keep only the fields and retention window required for your workflow. Limit sensitive dataset access to the smallest set of users and services. Avoid logging full payloads or sensitive fields in application and audit logs. Apply your internal security, legal, and compliance controls to this API data. # Introduction Source: https://docs.defendis.com/api/index Defendis API lets you integrate external threat signals into your product and security workflows to automate monitoring and enrichment. Use this API to: Query data leak signals for approved identifiers (domains, BINs, etc). Create and manage watchlists that define what you monitor. Analyse your external exposure and track ransomware activity. ## Base URL and versioning * Base URL: `https://api.defendis.com` * Version prefix: `/api/v1` Example endpoint: `https://api.defendis.com/api/v1/watchlists` ## Authentication All `/api/v1/*` endpoints require an API key: ```http theme={null} Authorization: Bearer ``` ## Start here Make your first request and learn integration patterns. API keys, authorization scope, and security best practices. Guidance on which endpoint family to use, with OpenAPI reference. Error model, retry behavior, and troubleshooting. Availability, versioning policy, and change management. ## Downloads * Download the `Postman file` * Import the OpenAPI spec URL: `https://api.defendis.com/openapi.json` # Changelog Source: https://docs.defendis.com/changelog ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Navigation and usability improvements and integration enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved API integration access and configuration flows ### Navigation and usability improvements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks ### Navigation and usability improvements and alerting enhancements * Improved navigation and overall usability * Smoother interactions in frequently used areas * Better user flow for common product tasks * Improved reliability of notifications and alerts ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Integration access and developer experience improvements and security enhancements * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding * More reliable behavior for enterprise integration scenarios * Strengthened account access and verification flows ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Platform improvements * Improved overall product stability and reliability * Enhanced usability across key product areas * Performance and quality improvements in core features ### Service‑Provider Billing & Workspace Improvements * Introduced service‑provider‑managed billing for more flexible workspace payments * Enhanced billing breakdowns for clearer cost visibility * Improved signup and verification flow for a smoother onboarding experience * Fixed minor issues and refreshed documentation pages for better clarity ### Improved Billing * Enhanced billing management * General refinements for better reliability and maintainability ### Enhanced Billing, Security, and Workspace Controls * *Stronger account security:* Refined MFA and session handling to ensure smoother, more reliable authentication * Strengthened account access and verification flows ### Improved Access and reliability * Enhanced subscription permission checks for smoother access * Improved overall product stability and reliability ### Improved Trial License and Billing Display * Clearer display of billing amounts for all license types * Enhanced handling of trial licenses for a smoother experience * More accurate and transparent billing information throughout the app * Improved overall product stability and reliability ### Improved Reliability for Authentication Requests * Extended retry window for temporary authentication issues to reduce login interruptions * Enhances overall stability when network conditions are inconsistent * Provides a smoother sign-in experience with fewer transient errors * Improved overall product stability and reliability ### Improved Session Stability and Refresh Handling * Enhanced session handling ensures smoother reconnections and fewer interruptions * Provides a more reliable and consistent experience when working across multiple sessions * Strengthened account access and verification flows ### Improved Stability and Minor Enhancements * Enhanced overall app stability for a smoother experience * Fixed minor issues to improve reliability and performance * Optimized background processes for faster response times * Improved overall product stability and reliability ### Improved Billing, Authentication, and Subscription Experience * Smarter billing: Introduces catalog-based billing with flexible, document-level discounts * Smoother sign-in: Enhanced authentication retry flow and refined interface for better usability * Faster loading: Updated loading visuals and automatic fallback for terminal licenses ### Improved Billing and Access Experience * Enhanced billing workflows for greater accuracy and reliability * Streamlined access controls to ensure smoother user management * Minor performance and stability improvements across the platform * Improved API integration access and configuration flows ### Improved Deployment Security and Performance * Enhanced deployment process with secure Google Cloud integration * Improved reliability through updated service account management * Improved reliability of notifications and alerts * Better clarity when tracking important updates ### Improved Security, Streaming, and Workspace Controls * Enhanced session management with new logout options and smoother refresh handling * Strengthened workspace access controls with billing fallback for uninterrupted service * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced Member Notifications in Console * Introduces a new notifications feature for console members * Enables real-time updates and alerts directly within the console * Improves visibility and responsiveness for team activities * Delivers a smoother, more connected user experience ### Improved Billing, Permissions, and Workspace Management * Enhanced billing experience with new payment form states and improved Stripe integration * Added permission catalog service for more flexible access control * Improved workspace management with safer deletion and new catalog features * Improved API integration access and configuration flows ### Improved Workspace Experience * Introduced enhanced workspace management with clearer allocation and usage controls * Improved user and billing management capabilities for workspace administrators * Improved navigation and overall usability ### Improved Workspace Management and Onboarding * Introduced user verification and guided onboarding sessions for a smoother start * Enhanced invite acceptance and redirect flow for a more seamless joining experience * Improved session reliability and visual alignment in the header ### Improved Data Security and Billing Reliability * General stability and performance enhancements for smoother operations * Improved overall product stability and reliability * Enhanced usability across key product areas ### Improved Workspace Billing Sync * Reduces potential discrepancies in billing information * Provides a smoother experience when managing workspace billing changes * Improved navigation and overall usability ### Improved Search Efficiency and Workspace Access Alignment * Search updates are now faster and more responsive, reducing unnecessary refreshes * Overall experience is smoother with improved performance and reliability * Improved product responsiveness across key pages ### Improved Workspace Insights and Session Reliability * Enjoy smoother session experiences with enhanced refresh handling * Improved reliability and control for workspace management tasks * Improved API integration access and configuration flows ### Performance and Stability Improvements * Enhanced overall app responsiveness for a smoother experience * Improved reliability to reduce unexpected errors * Minor interface refinements for better usability * General maintenance updates to keep things running efficiently ### Workspace Stability Improvements * Improved handling of approved workspace differences to reduce unnecessary alerts * General stability and performance enhancements for smoother workspace operations * Improved navigation and overall usability ### Improved Enterprise Billing Accuracy and Data Access * Improved data retrieval for faster and more reliable billing information * Streamlined reconciliation process to reduce potential discrepancies * Improved overall product stability and reliability ### Improved Billing Options and License Sync * Added support for a **Free** billing status to simplify account management * Workspaces now automatically **synchronize license details**, ensuring accurate and up‑to‑date access * Enhancements improve transparency and reduce manual updates for workspace admins * Improved navigation and overall usability ### Improved Workspace Licensing and Error Handling * Introduced enhanced workspace licensing with updated data models * Improved reliability through better error handling and duplicate prevention * Streamlined membership updates to maintain consistency and accuracy * Refreshed documentation pages for clearer guidance ### Improved Reports * Generate reports with your enterprise avatar and default logo for a more personalized look * Analytics now automatically adapts to your region for more accurate insights * Improved export usability ### Improved reliability for notification counts * Notification counts now update more consistently, even in unstable network conditions * Enhanced error handling ensures smoother user experience when fetching notifications * Overall reliability and responsiveness of notifications have been improved ### Enhanced Authentication * Improved sign-in reliability with updated authentication flow * Provides a smoother and more secure reauthentication experience for users * Strengthened account access and verification flows ### Improved API and Watchlist Management * Added enterprise ID support to API calls for better integration and control * Enhanced watchlist domain management for more accurate tracking * Improved CVE asset matching to strengthen vulnerability insights * Improved API integration access and configuration flows ### Improved app stability, CVE Tools, and Ransomware Insights * Enhanced authentication, Improved performance, and clearer error feedback * Added ransomware victim summaries, detailed views, and country-based filtering for deeper insights * Strengthened account access and verification flows ### Improved Error Handling and Watchlist Enhancements * Enhanced watchlist functionality with enterprise-grade validation * Improved overall stability and consistency across the platform * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Performance and reliability improvements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions ### Improved performance and simplified app behavior * Streamlined app configuration for faster load times * Reduced unnecessary redirects to improve navigation * Enhanced reliability and consistency across user sessions * Improved navigation and overall usability ### Improved Authentication and Session Reliability * Added automatic redirection to help users recover sessions after cutover events * Enhanced session handling for smoother, more reliable sign-ins * Improved overall stability and continuity during authentication transitions * Strengthened account access and verification flows ### Improved Resource Management with Custom Cache Controls * Enhanced performance through smarter caching behavior * Faster load times and reduced redundant data requests * More consistent user experience when accessing stored resources * Improved navigation and overall usability ### Improved API performance and reliability * Enhanced API responsiveness with smarter rate limiting for task updates * Improved connection stability to ensure smoother, more consistent interactions * Delivers a faster and more reliable experience for high-volume API users * Improved API integration access and configuration flows ### Improved Task Status Tracking and Batch Updates * Enjoy more accurate and consistent task progress updates * Benefit from smoother monitoring of large-scale task operations * Improved API integration access and configuration flows ### Improved Enterprise Update Experience * Enhanced enterprise update process for smoother data management * General usability improvements for a faster, more reliable experience * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Improved Support Experience and Settings Enhancements * Introduced a new Support Overview for easier access to key support information * Enhanced Support Settings with clearer labels and a more intuitive layout * Streamlined navigation to help users manage support preferences more efficiently * Improved API integration access and configuration flows ### Improved Billing and watchlist management * Past due accounts are now subject to a 7 days grace period * More accurate scope validation and smoother loading states in your watchlist dropdown * Faster, more reliable interactions across tasks management * Improved API integration access and configuration flows ### Improved Chat User Identity and Settings * Enhanced Chat integration for more accurate user identification * Simplified configuration options for managing communication settings * Improved reliability and consistency in user messaging experiences * Strengthened account access and verification flows ### Improved Task Management and Session Handling * Enhanced task management experience with improved UI and selection tools * Improved session and authentication handling for more reliable logins and logouts ### Improved Dashboard Stability and Error Handling * Enhanced reliability of dashboard statistics display * Improved handling of unexpected data or connection issues * Reduced likelihood of dashboard errors impacting user experience * Improved reporting and export usability ### Improved Session Reliability and Fraud Detection * Enhanced session management for more reliable and secure user experiences * Updated billing documentation for clearer incident response guidance * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages ### Improved Fraud Detail Loading Performance * Faster loading times when viewing fraud details * Smoother experience when switching between fraud cases * Enhanced reliability and consistency in fraud data display * Improved product responsiveness across key pages ### Enhanced Fraud Management and Navigation * Updates fraud tabs and localization for a clearer, more consistent interface * Improved multilingual experience and terminology consistency * Clearer product wording across supported languages * Better readability in user-facing content ### Improved Subscription Stability and Error Handling * Enhanced reliability when managing enterprise subscriptions * Reduced likelihood of subscription errors and interruptions * Improved clarity of error messages for smoother user experience * Improved overall product stability and reliability ### Improved Host Node Display in Surface Maps * Host node visuals now render with consistent width for better clarity * Enhanced readability and alignment across different map views * Minor stability improvements for smoother map interactions * Improved overall product stability and reliability ### Enhanced Feed, Intelligence, and Map Experiences * Introduced a new integrated feed experience with improved performance and real-time updates * Expanded intelligence features with enhanced loading states and new airport country insights * Refreshed map visuals and improved key management for smoother navigation * Added richer surface map details, including DNS summaries and clearer host information ### Easily Delete Workspaces * Added the ability to permanently delete workspaces when no longer needed * Simplifies workspace management and keeps your environment organized * Ensures a smoother experience when cleaning up unused projects * Improved navigation and overall usability ### Integration access and developer experience improvements * Improved API integration to support more reliable connections * Increased overall stability and performance for development operations * Improved API integration access and configuration flows * Clearer developer documentation for faster onboarding ### Enhanced APIs, Subscriptions, and Surface Map * Introduced API subscriptions for easier integration and management * Added Surface Map API with improved navigation for better visibility * Expanded surface and vulnerability APIs with watchlist support * Improved scan time display and overall interface consistency ### Improved Navigation and Enterprise Search Enhancements * Enhanced header with refined enterprise search and clearer billing filters * Streamlined enterprise switching for smoother account transitions * Added new indicators and brand menu for better visibility and control * General performance and stability improvements across the platform ### Improved Enterprise Switching and Reliability * Enhanced enterprise account switching for a smoother experience * Improved error handling to reduce interruptions and ensure stability * Minor performance refinements for faster, more reliable workflows * Improved overall product stability and reliability ### Backend improvements * Added new billing filters for easier account management * Refined subscription handling for smoother plan updates * Improved date range formatting and clearer subscription type labels ### Improved Billing, Security, and Developer Experience * **Simplified billing management:** New tools and clearer UI for managing billing, quotas, and access * **Enhanced security settings:** Updated interface and improved user experience * **Better developer tools:** Updated API documentation for smoother integrations ### Developer Mode release with usability and export improvements * Released Developer Mode for advanced security exploration workflows * Improved navigation and overall usability across key product areas * Smoother interactions in frequently used screens * Improved reporting and export usability ### Enterprise API setup improvements * Improved enterprise ID handling in API integration settings * More reliable request behavior during integration setup * Smoother configuration experience for API administrators ### Watchlist and monitoring improvements and reporting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reporting and export usability ### API docs and access reliability improvements * Improved availability of API reference artifacts for integrators * Better consistency when loading integration resources * Smoother developer experience during API implementation ### Expanded API integration coverage * Improved API documentation coverage for integration use cases * Easier access to integration resources for implementation teams * Better clarity when validating supported integration paths ### Integration stability improvements * Improved reliability for API integration traffic handling * Better diagnostics support for troubleshooting integration issues * Smoother overall experience for connected applications ### Integration security and access improvements * Improved cross-origin access controls for safer integrations * Better protection for API integrations used across environments * More consistent behavior for authenticated integration requests ### Account security improvements and monitoring enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved watchlist management and indicator handling ### Performance and reliability improvements and security enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Strengthened account access and verification flows ### Threat intelligence experience improvements and performance updates * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information * Improved product responsiveness across key pages ### Watchlist and monitoring improvements and intelligence enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved threat intelligence views and data clarity ### Watchlist and monitoring improvements and security enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Strengthened account access and verification flows ### Performance and reliability improvements and alerting enhancements * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved reliability of notifications and alerts ### Notification and alerting improvements * Improved reliability of notifications and alerts * Better clarity when tracking important updates * More consistent alert behavior across product areas ### Account security improvements and reporting enhancements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage * Improved reporting and export usability ### Watchlist and monitoring improvements and alerting enhancements * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved reliability of notifications and alerts ### Reporting and export improvements and performance updates * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation * Improved product responsiveness across key pages ### Account security improvements * Strengthened account access and verification flows * Improved reliability of sign-in and verification experiences * Better account protection for day-to-day usage ### Watchlist and monitoring improvements and performance updates * Improved watchlist management and indicator handling * Better visibility and organization for monitored assets * Smoother review experience for monitored results * Improved product responsiveness across key pages ### Reporting and export improvements * Improved reporting and export usability * Faster access to shareable security insights * Better consistency in exported data presentation ### Performance and reliability improvements and localization updates * Improved product responsiveness across key pages * Better stability during everyday usage * Faster loading and smoother interactions * Improved multilingual experience and terminology consistency ### Threat intelligence experience improvements * Improved threat intelligence views and data clarity * Better investigation experience for security findings * More consistent presentation of risk-related information