DarkStrata API (1.0.1)

Download OpenAPI specification:

API Support: [email protected] License: Proprietary

The DarkStrata API provides programmatic access to your organisation's threat intelligence and security operations. Use it to manage monitored assets and domains, query compromised credential data, configure alerts and automated actions, administer user and asset groups, integrate with third-party tools via webhooks, and export data for downstream analysis.

API location

The base URL for all API requests is:

https://api.darkstrata.io/v1

Authentication

All API requests require an API key sent in the X-Api-Key header.

Sign up at app.darkstrata.io, generate an API key in Integrations > API Keys, and include it in your requests:

curl -X GET "https://api.darkstrata.io/v1/__gtg" \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json"

AI Agent Integration (MCP)

The DarkStrata API is also available as an MCP server for AI agents. Connect any MCP-compatible client to mcp.darkstrata.io/mcp using your API key to access tools, resources, and pre-built security workflows. See the MCP documentation for connection details.

Localisation

All API endpoints support the Accept-Language header. Error messages, validation responses, and other user-facing text are returned in the requested locale.

Supported locales: en (default), ca, de, es, fr, it, ja, ko, nl, pl, sl, zh

If the requested locale is not supported, the API falls back to English (en).

curl -X GET "https://api.darkstrata.io/v1/alerts" \
  -H "X-Api-Key: your_api_key_here" \
  -H "Accept-Language: de"

Error Responses

All error responses follow a consistent structure with a machine-readable error code and a localised human-readable message:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid username or password"
  }
}

Validation errors (HTTP 400) include field-level detail:

{
  "message": "Invalid input data",
  "errors": [
    { "field": "email", "message": "Must be a valid email address" }
  ]
}

Common error codes: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, PLAN_LIMIT_EXCEEDED, INTERNAL_SERVER_ERROR.

Alerts

Security alerts and incident management

/alerts

/alerts

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

status
string
Enum: "ACTIVE" "UNDER_INVESTIGATION" "CLOSED"

Filter by alert status

severity
string
Enum: "INFO" "LOW" "MEDIUM" "HIGH" "CRITICAL"

Filter by alert severity

alert_type
string
Enum: "CREDENTIAL_EXPOSURE" "CONFIRMED_PASSWORD_USE" "CONFIRMED_SUPPLIER_PASSWORD_USE" "GHOST_SEEN"

Filter by alert type

product
string

Filter by product slug or public_id (e.g. stealer-intel)

from_date
string <date-time>

Filter alerts from this date (ISO 8601)

to_date
string <date-time>

Filter alerts to this date (ISO 8601)

tactic
string^TA[0-9]{4}$
Example: tactic=TA0006

MITRE ATT&CK® tactic id. Keeps alerts whose mitre block has at least one technique under this tactic. Alerts raised before ATT&CK tagging never match.

technique
string^T[0-9]{4}(\.[0-9]{3})?$
Example: technique=T1555.003

MITRE ATT&CK® technique id (sub-techniques included, e.g. T1555.003). Keeps alerts whose mitre block lists this technique. Combine with tactic to require both. Alerts raised before ATT&CK tagging never match.

sort
string
Default: "generated_at"
Enum: "generated_at" "published_at" "acknowledged_at" "total_new_matches" "status" "severity"

Field to sort by

direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

organisation
string <uuid>

Filter by organisation public_id (requires access to the organisation)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/alerts/stats/attack

Distinct alert counts per ATT&CK tactic and technique over the last 90 days, read from each alert's mitre block. A technique under several tactics counts towards each. Alerts raised before ATT&CK tagging are not counted.

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "attack_version": "20.0",
  • "window_days": 90,
  • "tagged_alerts": 12,
  • "tactics": [
    ],
  • "techniques": [
    ]
}

/alerts/stats

/alerts/stats

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "active": 15,
  • "acknowledged": 8,
  • "closed": 42,
  • "total_matches_last_30_days": 387,
  • "unique_identifiers_last_30_days": 252,
  • "avg_matches_per_alert": 23.5
}

/alerts/{id}

/alerts/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Alert ID

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "title": "Credential Exposure: 3 Staff Accounts",
  • "description": "3 staff accounts (3 with active malware) exposed across 1 asset.",
  • "severity": "HIGH",
  • "status": "ACTIVE",
  • "alert_type": "CREDENTIAL_EXPOSURE",
  • "from_date": "2026-10-18T00:00:00Z",
  • "to_date": "2026-10-19T00:00:00Z",
  • "generated_at": "2026-10-19T06:00:03Z",
  • "published_at": "2026-10-19T06:00:03Z",
  • "total_new_matches": 4,
  • "unique_identifiers": 3,
  • "unique_assets_count": 1,
  • "stealer_match_count": 4,
  • "breach_match_count": 0,
  • "affected_assets": [
    ],
  • "breakdown_by_type": {
    },
  • "breakdown_by_source": {
    },
  • "breakdown_by_flow": {
    },
  • "mitre": {
    },
  • "domains": [
    ]
}

/alerts/{id}

/alerts/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Alert ID

Request Body schema: application/json
required
status
required
string
Enum: "ACTIVE" "UNDER_INVESTIGATION" "CLOSED"

New status for the alert

Responses

Request samples

Content type
application/json
{
  • "status": "ACTIVE"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "CLOSED",
  • "updated_at": "2024-01-15T09:45:00Z",
  • "acknowledged_at": "2024-01-08T15:30:00Z",
  • "closed_at": "2024-01-15T09:45:00Z",
  • "acknowledged_by_user": {
    },
  • "closed_by_user": {
    },
  • "last_modified_by_user": {
    }
}

/alerts/{id}

/alerts/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Alert ID

Responses

Response samples

Content type
application/json
{
  • "message": "Alert deleted successfully",
  • "id": "550e8400-e29b-41d4-a716-446655440000"
}

API Keys

API key self-service, including in-place secret rotation

/api/keys/generate

An API key may only mint keys for a tenant whose parent is an MSP partner, never for its own organisation. Target the tenant with organisation (or the x-impersonate-organisation header). The new key's permissions are capped at the calling key's. The secret is returned once.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
label
string [ 3 .. 64 ] characters
organisation
string <uuid>

Tenant organisation ID

scope
Array of strings

Permissions for the key; empty grants everything the tenant and the calling key allow

expires_at
string <date-time>
description
string <= 256 characters
accept_non_commercial_terms
boolean

Required when the tenant has no billing contract

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "organisation": "a4b97354-4e56-4723-bc0e-1f22b5fcbed6",
  • "scope": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "accept_non_commercial_terms": true
}

/api/keys/rotate

Replaces the secret of the API key used to authenticate this request. The key keeps its ID, name, and permissions; the old secret stops working immediately. The new secret is returned once and cannot be retrieved again. Only API-key sessions can call this endpoint.

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "key": "string",
  • "prefix": "string",
  • "permissions": [
    ]
}

Assets

Asset management, verification, and statistics

/assets

/assets

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

keyword
string

Filter assets by hostname keyword

status
string
Enum: "VERIFIED" "UNVERIFIED" "ERROR"

Filter by verification status

method
string
Enum: "DNS" "HTTP"

Filter by verification method

sort
string
Default: "created_at"

Field to sort by

direction
string
Default: "desc"

Sort direction

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/assets/bulk

/assets/bulk

Authorizations:
apiAuthentication
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ items <uuid > ]

Array of asset IDs to delete

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

/assets/bulk/resubmit-dns

/assets/bulk/resubmit-dns

Authorizations:
apiAuthentication
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ items <uuid > ]

Array of asset IDs to resubmit DNS verification

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

/assets/stats

/assets/stats

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "verified": 0,
  • "pending": 0,
  • "failed": 0
}

/assets/{id}

/assets/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Asset ID

Responses

Response samples

Content type
application/json
{
  • "id": "7f8d9e0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
  • "hostname": "example.com",
  • "created_at": "2024-01-01T10:00:00Z",
  • "verification": {
    }
}

/assets/{id}

/assets/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string

Asset ID to delete

Responses

/assets/{id}/resubmit-dns

/assets/{id}/resubmit-dns

Authorizations:
apiAuthentication
path Parameters
id
required
string

Asset ID

Responses

Response samples

Content type
application/json
{
  • "message": "DNS checking can only be resubmitted for assets in failed verification state (ERROR). Current state does not qualify for resubmission.",
  • "current_status": "VERIFIED"
}

Credential Check

Privacy-preserving stolen credential checking via k-anonymity

/credential-check/stats

Returns aggregate statistics about the credential database including unique record counts and last update time.

SDKs: Official SDKs are available at: https://github.com/darkstrata/darkstrata-sdks

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "unique_records": 15000000000,
  • "total_records": 25000000000,
  • "last_updated": "2024-12-15T10:30:00.000Z"
}

/credential-check/query

Privacy-preserving credential breach checking service using k-anonymity.

How it works:

  1. Hash your credential pair, split with a colon using SHA-256 i.e. SHA256(email:password)
  2. Send the first 5 or 6 hexadecimal characters as the prefix parameter
  3. Receive HMAC-protected results that match this prefix
  4. Use the returned X-HMAC-Key to verify your full hash against the results

Privacy guarantees:

  • Server never sees your full hash (only 5 or 6-char prefix)
  • Results are HMAC-protected to prevent correlation between requests
  • HMAC keys rotate hourly via time windows if no client key provided
  • All matching hashes are returned (no filtering server-side)

Full documentation and examples: For complete end-to-end implementation examples and detailed usage guide, login to the Admin UI: https://app.darkstrata.io/explorer/credentials-api

SDKs: Official SDKs are available at: https://github.com/darkstrata/darkstrata-sdks

Authorizations:
apiAuthentication
query Parameters
prefix
required
string [ 5 .. 6 ] characters ^[a-fA-F0-9]{5,6}$
Example: prefix=5baa61

First 5 or 6 hexadecimal characters of the SHA-256 hash to check. Case-insensitive (automatically normalised to uppercase). Using 6 characters returns ~16x fewer results than 5, reducing response size.

Examples:

  • 5-char: from hash 5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8 use 5baa6
  • 6-char: from the same hash use 5baa61
clientHmac
string >= 64 characters ^[a-fA-F0-9]{64,}$
Example: clientHmac=8a2f7b9e1c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f

Optional: Client-provided HMAC key for deterministic, consistent results across requests.

Use case: Some customers need consistent hash results over time for tracking or caching purposes. By providing your own HMAC key, the returned hashes will always be the same for the same input data, enabling result caching and comparison across time.

Security requirements:

  • Must be at least 64 hexadecimal characters (256 bits minimum)
  • Must be cryptographically random (high entropy)
  • Cannot be trivial patterns (all zeros, repeating characters, simple sequences)
  • Must contain at least 8 unique characters

If omitted or invalid: Falls back to server-generated HMAC with hourly rotation (time-windowed).

Best practices:

  • Generate using: openssl rand -hex 32 or equivalent
  • Store securely (treat as a secret)
  • Rotate periodically for security
  • Different keys for different use cases

Example generation (bash):

openssl rand -hex 32
# Output: 8a2f7b9e1c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f
since
integer >= 0
Example: since=20089

Optional: Filter results to only include entries added on or after this date.

Accepts either:

  • Epoch day (days since Unix epoch, Jan 1 1970): e.g., 20089 = Jan 1, 2025
  • Unix timestamp (seconds since epoch): e.g., 1735689600 = Jan 1, 2025

Auto-detection: Values > 100000 are treated as Unix timestamps and converted.

Use cases:

  • Incremental monitoring: "What's new since my last check?"
  • Filtering old data: "Only data imported from 2024 onwards"

Example:

# Using epoch day (Jan 1, 2025)
?prefix=5baa6&since=20089

# Using Unix timestamp (Jan 1, 2025)
?prefix=5baa6&since=1735689600

Note: If omitted, returns all matching entries regardless of when they were added.

Responses

Response samples

Content type
application/json
[
  • "8A2F7B9E1C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0C1D2E3F4A5B6C7D8E9F",
  • "B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4",
  • "C5D6E7F8A9B0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6"
]

Dashboard

Dashboard data and analytics

/dashboard

/dashboard

Authorizations:
apiAuthentication
query Parameters
days
string
Default: "7"

Number of days to look back for statistics

Responses

Response samples

Content type
application/json
{
  • "period_days": 7,
  • "assets_added": 3,
  • "assets_verified": 2,
  • "pending_users": 1,
  • "new_alerts": 0
}

/dashboard/exposure-summary

Aggregates the organisation's infostealer credential-exposure events (across its verified monitored assets) into headline metrics: total vs critical events, customers (inbound) vs employees (outbound), and the most-exposed services. The "breach" figure under sources counts third-party breach-corpus exposures (breach_exposures) for the org — surfaced alongside infostealer for comparison but NOT included in the infostealer event total (breaches carry no employee/ customer attribution). Suppressed when source=MALWARE. Only actionable records (status NEW or RE_EMERGED) are counted; triaged-away records (RESOLVED, IGNORED, FALSE_POSITIVE) are excluded, mirroring the explorer's default view.

Authorizations:
apiAuthentication
query Parameters
from
string

Inclusive start of the event date range (ISO 8601). Omit for all-time.

to
string

Inclusive end of the event date range (ISO 8601). Omit for all-time.

asset_ids
string

Comma-separated asset public IDs to scope the summary to.

source
string
Enum: "MALWARE" "BREACH"

Restrict to a single source type (MALWARE = infostealer, BREACH = data breach).

top_limit
string
Default: "5"

Number of services to return in top_services (1-25).

Responses

Response samples

Content type
application/json
{
  • "events": {
    },
  • "distribution": {
    },
  • "sources": {
    },
  • "top_services": [
    ]
}

Data Intelligence

Intelligence data and threat analysis

/data-intelligence/breaches/stats

Counts of breach exposures (BreachExposure rows) for the calling organisation, broken down by status, threat score, and combolist-vs-genuine corpus. Companion to /data-intelligence/stats which covers stealer-log data; this endpoint covers the second OUTBOUND data source — third-party breaches indexed against monitored hostnames. PII is never returned, only presence flags.

Authorizations:
apiAuthentication
query Parameters
hostnames
string

Comma-separated monitored hostnames

threat_scores
string

Comma-separated breach threat score levels (1-5)

identifier_status
string

Comma-separated statuses (NEW, RESOLVED, IGNORED, FALSE_POSITIVE, RE_EMERGED)

is_combolist
string
Enum: "true" "false"

Restrict to combolist or genuine-breach corpora only

has_plaintext_password
string
Enum: "true" "false"

Restrict to rows with a recovered plaintext password

identifier_keyword
string

Substring match against identifier (case-insensitive)

alert_id
string

Scope results to the breach exposures that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no breach matches.

group_by
string
Value: "identifier"

When 'identifier', aggregate stats at the (identifier, asset) level so the headline numbers match the grouped table view (dominant status per group, max threat score per group, any-flag for combolist/plaintext).

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid input data",
  • "errors": [
    ]
}

/data-intelligence/breaches/query

Paginated list of BreachExposure rows for the calling organisation. Each row carries presence flags for every PII field (booleans only — values are never stored or returned), the corpus combolist flag, the password-strength score (null until PasswordStrengthWorker has scored it), and the breach threat score level. Companion to /data-intelligence/query, which covers stealer logs.

Response is a discriminated union on mode:

  • mode: "rows" — one row per exposure (default)
  • mode: "identifiers" — one row per identifier (when group_by=identifier), with aggregated counts. Filters are pre-group: e.g. threat_scores=5 returns identifiers whose at-least-one child exposure is level 5, not those whose worst is 5.
Authorizations:
apiAuthentication
query Parameters
page
string
limit
string
sort
string
Enum: "last_seen_at" "first_seen_at" "breach_threat_score_level_id" "identifier" "corpus_breach_year"
direction
string
Enum: "asc" "desc"
hostnames
string
threat_scores
string
identifier_status
string
is_combolist
string
Enum: "true" "false"
has_plaintext_password
string
Enum: "true" "false"
identifier_keyword
string
alert_id
string

Scope results to the breach exposures that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no breach matches.

group_by
string
Value: "identifier"

When set to identifier, collapse to one row per identifier with aggregated counts.

format
string
Default: "json"
Enum: "json" "csv"

Response format. json returns the paginated discriminated union; csv streams a full export (one row per exposure, or one row per identifier+asset pair when group_by=identifier). CSV requires csv-download access on the calling org's plan.

csv_fields
string

Comma-separated list of CSV field names to include (e.g., "public_id,identifier,hostname"). When omitted, all fields are exported. Ignored for json responses.

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid input data",
  • "errors": [
    ]
}

/data-intelligence/breaches/bulk-status

Updates the status on a set of BreachExposure rows in one request. Accepts EITHER public_ids (direct list of exposures) OR identifier_groups (each entry fans out to every child exposure matching identifier+asset within the caller's organisation — the entry-point for the grouped view's bulk actions). Mixed payloads are rejected. Status transitions follow the same closed-state bookkeeping as the single-row PATCH (resolved_at / status_changed_at). Audit events are emitted one per affected child row, tagged with bulk_group_identifier when the identifier_groups path was used so the timeline UI can collapse them.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
status
required
string
Enum: "NEW" "RESOLVED" "IGNORED" "FALSE_POSITIVE" "RE_EMERGED"
public_ids
Array of strings <uuid> [ items <uuid > ]

Direct list of BreachExposure public_ids to update.

Array of objects

Each entry expands to every child exposure matching identifier+asset within the org.

Responses

Request samples

Content type
application/json
{
  • "status": "NEW",
  • "public_ids": [
    ],
  • "identifier_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "affected": 0,
  • "status": "string"
}

/data-intelligence/breaches/threat-score-rationale

Returns the human-readable signals that produced each child exposure's score plus the identifier-level signals that may have bumped or capped them. Mirrors the inputs of the worker scorer (platform/workers/.../breach-exposure/scoring.ts) but does not re-score — the stored breach_threat_score_level_id is the source of truth.

Authorizations:
apiAuthentication
query Parameters
identifier
required
string

Identifier (email / username). Normalised to lowercase server-side.

asset_id
required
string

Asset public_id. Must belong to the caller's organisation.

Responses

Response samples

Content type
application/json
{
  • "identifier": "string",
  • "asset": {
    },
  • "max_score": 0,
  • "overall_reasons": [
    ],
  • "exposures": [
    ]
}

/data-intelligence/stats

/data-intelligence/stats

Authorizations:
apiAuthentication
query Parameters
flow
string
Enum: "INBOUND" "OUTBOUND"

Filter by data flow direction

months
number [ 1 .. 12 ]
Default: 6

Number of months to include in trends

asset_id
string

Filter by asset ID

is_matching_naming_rule
string
Enum: "true" "false"

Filter by naming rule match

show_junk
string
Enum: "true" "false"

Include junk records in statistics

start_date
string <date-time>

Filter by start date (ISO 8601 format)

end_date
string <date-time>

Filter by end date (ISO 8601 format)

credential_type
string
Enum: "EP" "UP"

Filter by credential type

keyword
string

Search by identifier keyword (case-insensitive)

is_matching_groups
string
Enum: "true" "false"

Filter by group member match status

threat_score
string

Filter by exact threat score level (1-5, where 1=Info, 2=Needs Review, 3=Medium, 4=High, 5=Critical)

threat_score_min
string

Minimum threat score filter (inclusive, 1-5)

threat_score_max
string

Maximum threat score filter (inclusive, 1-5)

threat_scores
string

Comma-separated list of threat score levels to include (e.g., "1,2,3,4,5")

hostnames
string

Comma-separated list of full hostnames to filter by (e.g., "mail.example.com,portal.example.com"). For INBOUND flow, filters by the constructed hostname (subdomain + apex domain). Only valid hostname characters are accepted (alphanumeric, dots, hyphens).

alert_id
string

Scope stats to the stealer-log records that contributed to a specific alert (public_id).

Responses

Response samples

Content type
application/json
{
  • "overview": {
    },
  • "trends": {
    },
  • "metrics": {
    },
  • "groups": {
    },
  • "domains": {
    },
  • "services": {
    },
  • "threat_score_stats": {
    }
}

/data-intelligence/hostnames

Fetches all unique hostnames (subdomain + apex domain) with their credential match counts for INBOUND flow (Compromised Customers). Use this endpoint to populate hostname filter pills in the UI. A hostname is the full domain name including any subdomain prefix (e.g., "mail.example.com" or just "example.com" if no subdomain).

Authorizations:
apiAuthentication
query Parameters
asset_id
string

Optional asset public ID to filter hostnames for a specific monitored asset

alert_id
string

Scope hostnames to the stealer-log records that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no stealer matches.

keyword
string

Search by identifier keyword (case-insensitive)

hostname_search
string

Substring filter against hostname (case-insensitive)

show_junk
string
Enum: "true" "false"

Include low-quality/junk records

start_date
string <date-time>

Filter by start date (ISO 8601 format)

end_date
string <date-time>

Filter by end date (ISO 8601 format)

credential_type
string
Enum: "EP" "UP"

Filter by credential type

is_matching_naming_rule
string
Enum: "true" "false"

Filter by naming rule match

is_matching_groups
string
Enum: "true" "false"

Filter by group member match status

threat_scores
string

Comma-separated list of threat score levels to include (e.g., "1,2,3,4,5")

identifier_status
string

Comma-separated identifier status filter (NEW, RESOLVED, IGNORED, FALSE_POSITIVE, RE_EMERGED, FLAGGED)

is_password_reuser
string
Enum: "true" "false"

Filter to only show identifiers who reuse passwords across different services

Responses

Response samples

Content type
application/json
{
  • "hostnames": [
    ],
  • "total_match_count": 26
}

/data-intelligence/query

/data-intelligence/query

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

asset_id
string

Filter by asset ID

alert_id
string

Scope results to the stealer-log records that contributed to a specific alert (public_id). Joins through organisation_alert_matches. Returns zero rows if the alert does not exist or has no stealer matches.

group_ids
Array of strings

Filter by specific group IDs

include_password_variants
string
Enum: "true" "false"

Include password variants in response

junk_score_min
string

Minimum junk score filter

junk_score_max
string

Maximum junk score filter

keyword
string

Search by identifier keyword (case-insensitive)

start_date
string <date-time>

Filter by start date (ISO 8601 format)

end_date
string <date-time>

Filter by end date (ISO 8601 format)

flow
string
Enum: "INBOUND" "OUTBOUND"

Filter by flow direction. If not specified, returns all flows.

credential_type
string
Enum: "EP" "UP"

Filter by credential type

type
string
Default: "json"
Enum: "json" "csv"

Response type. json returns the paginated list; csv streams a full export of the same list — every filter and the sort apply exactly as for json (only page/limit are ignored). Rows are grouped the same way: one row per identifier, represented by its most recent matching record, with per-identifier matched_service_count and password_variant_count columns. For one row per identifier/service event use GET /data-intelligence/events/query?format=csv instead. Plans with a query row cap receive at most that many rows, in the default sort. CSV requires csv-download access.

csv_fields
string

Comma-separated CSV columns (default: all). Available: id, asset_id, hostname, identifier, junk_score, threat_score, base_threat_score, provenance_label, matched_corpora_count, earliest_match_year, combolist_confidence, is_matching_naming_rule, is_logging_into_monitored_asset, is_in_any_group, is_in_priority_group, password_strength_score, credential_type, service_type, source, flow, created_at, matched_member_id, matched_group_name, matched_at, asset_group_name, asset_group_category, identifier_domain_group_name, identifier_domain_group_category, matched_service_count, password_variant_count.

sort
string
Enum: "identifier" "domain" "junk_score" "threat_score_level_id" "created_at" "effective_priority" "matched_service_count"

Sort field (default effective_priority DESC — actionable items first, then by threat score)

direction
string
Enum: "asc" "desc" "ASC" "DESC"

Sort direction (case insensitive)

is_matching_naming_rule
string
Enum: "true" "false"

Filter by naming rule match

is_matching_groups
string
Enum: "true" "false"

Filter by group member match status

threat_score
string

Filter by exact threat score level (1-5, where 1=Info, 2=Needs Review, 3=Medium, 4=High, 5=Critical)

threat_score_min
string

Minimum threat score filter (inclusive, 1-5)

threat_score_max
string

Maximum threat score filter (inclusive, 1-5)

threat_scores
string

Comma-separated list of threat score levels to include (e.g., "1,2,3,4,5")

identifier_status
string

Comma-separated identifier status filter — NEW, RESOLVED, IGNORED, FALSE_POSITIVE, RE_EMERGED. Use "FLAGGED" to show all non-NEW statuses.

is_password_reuser
string
Enum: "true" "false"

Filter to only show identifiers who reuse passwords across different services

hostnames
string

Comma-separated list of full hostnames to filter by (e.g., "mail.example.com,portal.example.com"). For INBOUND flow, filters by the constructed hostname (subdomain + apex domain). Only valid hostname characters are accepted (alphanumeric, dots, hyphens).

Responses

Response samples

Content type
[
  • {
    },
  • {
    }
]

/data-intelligence/navigation-context/{id}

Returns the position, total count, and adjacent record IDs for an identifier within a filtered dataset. Uses SQL window functions for efficient navigation without fetching all record IDs. Supports all the same filters as the query endpoint.

Authorizations:
apiAuthentication
path Parameters
id
required
string

The public_id of the domain_data_identifier record

query Parameters
alert_id
string

Scope navigation to the stealer-log records that contributed to a specific alert (public_id). Returns 404 when the target id is outside the alert's matches.

asset_id
string

Filter by asset public ID

flow
string
Enum: "INBOUND" "OUTBOUND"
keyword
string
show_junk
string
Enum: "true" "false"
junk_score_max
string
start_date
string <date-time>
end_date
string <date-time>
credential_type
string
Enum: "EP" "UP"
is_matching_naming_rule
string
Enum: "true" "false"
is_matching_groups
string
Enum: "true" "false"
threat_scores
string
identifier_status
string

Comma-separated identifier status filter

is_password_reuser
string
Enum: "true" "false"
hostnames
string

Comma-separated hostnames to filter by

sort
string
Enum: "identifier" "domain" "junk_score" "threat_score_level_id" "created_at" "effective_priority" "matched_service_count"
direction
string
Enum: "asc" "desc" "ASC" "DESC"

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid input data",
  • "errors": [
    ]
}

/data-intelligence/individual/{id}

Returns stealer-side activity for the identifier plus a breach_exposures array — one row per third-party-corpus exposure linked to this identifier (same row shape as /data-intelligence/breaches/query mode: rows). Capped at 200 rows; breach_exposure_count_truncated is true when the cap was hit.

Authorizations:
apiAuthentication
path Parameters
id
required
string

The public_id (GUID) of a domain data match record

query Parameters
asset_id
string

Optional asset public_id to scope the lookup

Responses

/data-intelligence/individual/{id}/ai-summary

/data-intelligence/individual/{id}/ai-summary

Authorizations:
apiAuthentication
path Parameters
id
required
string

The public_id (GUID) of the identifier

Responses

/data-intelligence/malware-family/{family}/profile

/data-intelligence/malware-family/{family}/profile

Authorizations:
apiAuthentication
path Parameters
family
required
string

The malware family name (e.g. redline, vidar, raccoon)

Responses

/data-intelligence/bulk-delete

Performs a soft delete on multiple domain data match records by setting deleted_at timestamp. Records are not permanently deleted but will be excluded from all queries and statistics. Maximum of 2000 records can be deleted in a single request.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
ids
required
Array of strings [ 1 .. 2000 ] items

Array of public IDs to soft delete (maximum 2000)

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "deleted_count": 0
}

/data-intelligence/identifiers/{id}

/data-intelligence/identifiers/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string

Public ID of the identifier record

Responses

/data-intelligence/identifiers/{id}

/data-intelligence/identifiers/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string

Public ID of the identifier record

Request Body schema: application/json
required
status
string
Enum: "NEW" "RESOLVED" "IGNORED" "FALSE_POSITIVE" "RE_EMERGED"
notes
string or null
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "status": "NEW",
  • "notes": "string",
  • "tags": [
    ]
}

/data-intelligence/identifiers/{id}/actions

Retrieves the completion status of recommended actions for an identifier record

Authorizations:
apiAuthentication
path Parameters
id
required
string

Public ID of the identifier record

query Parameters
flow
string
Enum: "INBOUND" "OUTBOUND"

Flow direction — if omitted, auto-detected from match data

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "completed_count": 0,
  • "total_count": 0
}

/data-intelligence/identifiers/{id}/actions

Updates the completion status of recommended actions for an identifier record

Authorizations:
apiAuthentication
path Parameters
id
required
string

Public ID of the identifier record

query Parameters
flow
string
Enum: "INBOUND" "OUTBOUND"

Flow direction — if omitted, auto-detected from match data

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "actions": [
    ],
  • "completed_count": 0,
  • "total_count": 0
}

Groups

Group management for organising users and assets. Groups can be of two types:

  • USERS groups: Contain user identities (email, username, employee ID, phone, or custom identifiers) for monitoring employee credentials
  • ASSETS groups: Contain hostnames or asset identifiers for monitoring infrastructure and devices

/groups

Retrieve a paginated list of groups within your organisation. Groups can be filtered by type:

  • USERS groups contain user identities (emails, usernames, employee IDs, etc.) for monitoring employee credentials and exposure
  • ASSETS groups contain hostnames or asset identifiers for monitoring infrastructure assets
Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

keyword
string

Filter groups by name keyword

sync_source
string
Enum: "MANUAL" "GOOGLE_GROUPS" "GOOGLE_WORKSPACE" "AZURE_AD" "ACTIVE_DIRECTORY" "LDAP" "BULK_IMPORT" "API"

Filter by sync source

group_type
string
Enum: "USERS" "ASSETS"

Filter by group type. USERS groups contain user identities (email, username, etc.), ASSETS groups contain hostnames or asset identifiers.

sync_status
string
Enum: "ACTIVE" "DISABLED" "ERROR" "PENDING_SETUP"

Filter by sync status

sort
string
Default: "created_at"

Field to sort by

direction
string
Default: "desc"

Sort direction

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

/groups

/groups

Authorizations:
apiAuthentication
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Group name (must be unique within organisation)

description
string <= 1000 characters

Optional group description

is_priority
boolean
Default: false

Whether this is a priority group

group_type
string
Default: "USERS"
Enum: "USERS" "ASSETS"

Type of group. Use USERS for user/identity groups (email, username, employee ID, phone, custom identifiers). Use ASSETS for hostname/asset groups. Asset groups only support manual member management.

sync_source
string
Default: "MANUAL"
Enum: "MANUAL" "GOOGLE_GROUPS" "GOOGLE_WORKSPACE" "AZURE_AD" "ACTIVE_DIRECTORY" "LDAP" "BULK_IMPORT" "API"

Source of group synchronization. Note that ASSETS groups only support MANUAL sync.

sync_config
object

Sync-specific configuration (JSON object)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Security Team",
  • "description": "Information security and compliance team",
  • "is_priority": true,
  • "group_type": "USERS",
  • "sync_source": "MANUAL",
  • "sync_config": { }
}

Response samples

Content type
application/json
{
  • "id": "770e8400-e29b-41d4-a716-446655440002"
}

/groups/{id}

/groups/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Group ID

Responses

Response samples

Content type
application/json
Example
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Engineering Team",
  • "description": "All engineering staff members",
  • "group_type": "USERS",
  • "sync_source": "GOOGLE_WORKSPACE",
  • "sync_status": "ACTIVE",
  • "sync_error": null,
  • "sync_config": {},
  • "last_synced_at": "2025-11-06T10:30:00.000Z",
  • "member_count": 42,
  • "created_by": {},
  • "created_at": "2025-10-01T08:00:00.000Z",
  • "updated_at": "2025-11-06T10:30:00.000Z"
}

/groups/{id}

/groups/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Group ID

Request Body schema: application/json
required
name
string
description
string
sync_source
string
Enum: "MANUAL" "GOOGLE_GROUPS" "GOOGLE_WORKSPACE" "AZURE_AD" "ACTIVE_DIRECTORY" "LDAP" "BULK_IMPORT" "API"
sync_config
object
sync_status
string
Enum: "ACTIVE" "DISABLED" "ERROR" "PENDING_SETUP"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "sync_source": "MANUAL",
  • "sync_config": { },
  • "sync_status": "ACTIVE"
}

/groups/{id}

/groups/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Group ID to delete

Responses

/groups/{id}/members

Upload group members using multiple formats: JSON, CSV (inline or file upload).

Group Types:

  • USERS groups: Members are user identities (emails, usernames, employee IDs, etc.)
  • ASSETS groups: Members are hostnames or asset identifiers

Modes:

  • add (default): Appends new members to existing ones
  • replace: Removes all existing members first, then adds the new ones

CSV Format Options:

  1. Simple CSV (single column): Just email addresses, hostnames, or identifiers, one per line
  2. CSV with headers: Use columns like identifier, identifier_type, display_name, external_id, metadata
  3. Flexible headers: Column names like email, username, user, member, or hostname are auto-detected
  4. Profile columns (user groups): job_title, department, company_name, employee_id, employee_type, office_location, city, country, manager_name, manager_email, mobile_phone, business_phone. Header matching is case-insensitive and ignores spaces/underscores (Job Title, job_title and jobTitle are equivalent). Values are stored in member metadata under the same keys populated by Entra ID and Google Workspace sync, so manually imported and directory-synced members are enriched identically. Empty cells are ignored.

Content-Type Options:

  • application/json: Standard JSON with members array
  • text/csv: CSV content in request body
  • text/plain: Plain text CSV content
  • multipart/form-data: Upload CSV file

Limits:

  • Maximum 1000 members per request
  • Maximum 10MB file size for uploads
Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Group ID

query Parameters
mode
string
Default: "add"
Enum: "add" "replace"

add: Append new members (duplicates ignored)

replace: Remove all existing members and add new ones

Request Body schema:
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
Example
{
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "added_count": 45,
  • "duplicate_count": 5,
  • "removed_count": 20,
  • "total_submitted": 50,
  • "message": "45 members added successfully, 5 duplicates ignored"
}

/groups/{id}/members

/groups/{id}/members

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Group ID

query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

keyword
string

Filter members by identifier or display name

identifier_type
string
Enum: "EMAIL" "USERNAME" "EMPLOYEE_ID" "PHONE" "CUSTOM" "HOSTNAME"

Filter by identifier type. For USERS groups use EMAIL, USERNAME, EMPLOYEE_ID, PHONE, or CUSTOM. For ASSETS groups use HOSTNAME.

status
string
Enum: "ACTIVE" "INACTIVE" "PENDING" "REMOVED"

Filter by member status

sort
string
Default: "added_at"

Field to sort by

direction
string
Default: "desc"

Sort direction

Responses

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

/groups/{id}/members/{member_id}

/groups/{id}/members/{member_id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Group ID

member_id
required
string <uuid>

Member ID

Request Body schema: application/json
required
display_name
string
status
string
Enum: "ACTIVE" "INACTIVE" "PENDING" "REMOVED"
external_id
string
metadata
object

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "status": "ACTIVE",
  • "external_id": "string",
  • "metadata": { }
}

/groups/{id}/members/{member_id}

/groups/{id}/members/{member_id}

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Group ID

member_id
required
string <uuid>

Member ID to remove

Responses

/groups/{id}/members/move

/groups/{id}/members/move

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Source group ID

Request Body schema: application/json
required
target_group_id
required
string <uuid>

Target group ID to move members to

member_ids
required
Array of strings <uuid> [ items <uuid > ]

Array of member IDs to move

Responses

Request samples

Content type
application/json
{
  • "target_group_id": "efc47beb-e46d-465e-921d-3e02578ccf22",
  • "member_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "moved_count": 0,
  • "duplicate_count": 0,
  • "message": "string"
}

Incident Response

Domain credential export for incident response, including PGP key management

/incident-response

Request a new incident response export for an apex domain. This will search for outbound credential data across the domain and all its subdomains, package it into an encrypted archive, and make it available for download. Exports are subject to an annual quota. Freemail domains (e.g. gmail.com, yahoo.com) and popular public domains (e.g. google.com, facebook.com) are blocked. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
domain
required
string

Apex domain to export credential data for (e.g. example.com). Subdomains are automatically stripped.

attestation_full_name
required
string [ 2 .. 200 ] characters

Full legal name of the person making the attestation

attestation_title
required
string [ 2 .. 200 ] characters

Job title of the person making the attestation

attestation_company
required
string [ 2 .. 200 ] characters

Company of the person making the attestation

attestation_reason_type
required
string
Enum: "PENTEST" "SECURITY_AUDIT" "INCIDENT_RESPONSE" "COMPLIANCE" "LEGAL_REQUEST" "OTHER"

Reason for requesting the export

attestation_reason
string <= 2000 characters

Additional justification (required when reason_type is OTHER)

attestation_accepted
required
boolean
Value: true

Must be true to confirm legal attestation

encryption_method
string
Enum: "PASSWORD_ZIP" "SEVEN_ZIP" "PGP"

Archive encryption method. Defaults to PGP when pgp_key_id is supplied, otherwise PASSWORD_ZIP. PGP requires pgp_key_id.

pgp_key_id
string <uuid>

Public ID of the organisation PGP key to encrypt with (from GET /organisations/{id}/pgp-keys). Required when encryption_method is PGP.

Responses

Request samples

Content type
application/json
{
  • "domain": "example.com",
  • "attestation_full_name": "string",
  • "attestation_title": "string",
  • "attestation_company": "string",
  • "attestation_reason_type": "PENTEST",
  • "attestation_reason": "string",
  • "attestation_accepted": true,
  • "encryption_method": "PASSWORD_ZIP",
  • "pgp_key_id": "9f9f2234-160b-42dc-be31-a99205435b67"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "domain": "string",
  • "status": "PENDING",
  • "encryption_method": "PASSWORD_ZIP",
  • "created_at": "2019-08-24T14:15:22Z",
  • "archive_password": "string",
  • "password_warning": "string"
}

/incident-response

List incident response exports for your organisation. Results are paginated. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page

status
string
Enum: "PENDING" "PROCESSING" "COMPLETED" "FAILED" "EXPIRED"

Filter by export status

domain
string

Filter by domain (case-insensitive contains match)

include_deleted
boolean
Default: false

Include soft-deleted exports (for audit). Their archives are gone and cannot be downloaded.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/incident-response/stats

Get annual usage statistics for incident response exports. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "completed": 0,
  • "used": 0,
  • "deleted": 0,
  • "remaining": 0,
  • "limit": 0,
  • "usage_percentage": 0,
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z"
}

/incident-response/{id}

Get detailed information about a specific incident response export, including attestation details and download history. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Export public ID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "domain": "string",
  • "status": "PENDING",
  • "encryption_method": "PASSWORD_ZIP",
  • "record_count": 0,
  • "file_size_bytes": 0,
  • "download_count": 0,
  • "last_downloaded_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "pgp_key_fingerprint": "string",
  • "has_password": true,
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "processing_completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "attestation": {
    },
  • "requested_by": {
    },
  • "downloads": [
    ]
}

/incident-response/{id}/password

Retrieve the archive password for a password-encrypted incident response export. Only available for exports using PASSWORD_ZIP or SEVEN_ZIP encryption methods. This action is audit-logged at HIGH severity. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Export public ID

Responses

Response samples

Content type
application/json
{
  • "archive_password": "string"
}

/incident-response/{id}/download

Returns a short-lived presigned URL for the encrypted export archive. The export must be COMPLETED and not expired. Every call is recorded against the export's download history and audit-logged at CRITICAL severity. This feature is not available on standard plans and is only enabled for approved partners. Contact hello@darkstrata.io to enable this feature.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Export public ID

Responses

Response samples

Content type
application/json
{
  • "download_url": "string"
}

/incident-response/bulk

Soft-deletes the given exports and removes their archives from storage. Deleted exports still count towards the annual quota.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

/incident-response/bulk/invalidate

Immediately expires the given exports and removes their archives from storage. Use as a kill switch when an export should no longer be downloadable.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "invalidated": 0
}

/incident-response/bulk/download

Returns presigned URLs for each COMPLETED, unexpired export in the list. Exports that are not downloadable are skipped and counted. Downloads are recorded and audit-logged.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "downloads": [
    ],
  • "skipped": 0
}

/organisations/{id}/pgp-keys

List the organisation's PGP public keys. Any of these may be chosen (by id) as the encryption key when requesting a PGP-encrypted incident response export.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Organisation public ID

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

/organisations/{id}/pgp-keys

Add a PGP public key to the organisation. An organisation may hold several keys; the key to encrypt with is chosen per export via pgp_key_id. Requires organisations:write permission.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Organisation public ID

Request Body schema: application/json
required
pgp_public_key
required
string

Armoured PGP public key (must include BEGIN/END PGP PUBLIC KEY BLOCK headers)

label
string <= 100 characters

Optional friendly name for the key (e.g. "SOC team 2026")

Responses

Request samples

Content type
application/json
{
  • "pgp_public_key": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "key": {
    }
}

/organisations/{id}/pgp-keys/{key_id}

Remove one of the organisation's PGP public keys. Past exports remain encrypted with the key they were created with.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Organisation public ID

key_id
required
string <uuid>

PGP key public ID

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Lens

Credential exposure notifications for individuals

/lens/invite/send

Send Lens invitation emails to one or more identifiers. Creates invitation tokens valid for 7 days and sends personalised emails to each recipient.

By default, identifiers that have already completed their Lens review are skipped. Set include_completed: true to re-invite users who have already completed.

Accepts either a single identifier ID or an array of identifier IDs for bulk sending.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
identifier_id
string <uuid>

Single identifier public ID (use this OR identifier_ids, not both)

identifier_ids
Array of strings <uuid> [ items <uuid > ]

Array of identifier public IDs for bulk sending (use this OR identifier_id, not both)

include_completed
boolean
Default: false

If true, send invitations even to identifiers that have already completed their review

Responses

Request samples

Content type
application/json
{
  • "identifier_id": "a400f51e-8863-4890-9fd3-3f462d124526",
  • "identifier_ids": [
    ],
  • "include_completed": false
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "sent": 0,
  • "skipped_completed": 0,
  • "skipped_invalid": 0,
  • "emails": []
}

/lens/token/{tokenId}

Revoke an active lens invitation token. Only tokens that are still pending (not used, expired, or already revoked) can be revoked.

Authorizations:
apiAuthentication
path Parameters
tokenId
required
string <uuid>

Public ID of the lens token to revoke

Responses

Response samples

Content type
application/json
{
  • "message": "Token revoked successfully"
}

Organisations

Organisation management and multi-tenancy

/organisations

/organisations

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

keyword
string

Filter organisations by keyword

type
string
Enum: "INDIVIDUAL" "TEAM" "MSP" "RESELLER"

Filter organisations by type

billing_status
string
Enum: "active" "trial" "trial_expired" "manual" "no_plan" "pending" "past_due" "suspended" "canceled" "expired"

Filter organisations by billing status

activity
string
Enum: "new" "engaged" "dormant" "no_login"

Filter by customer activity. Buckets are mutually exclusive — new (registered in the last 7 days), otherwise engaged (a user signed in within 30 days), dormant (no sign-in for 30+ days) or no_login (no user has ever signed in)

credential_checks
string
Value: "near_limit"

near_limit: organisations that have used 80% or more of their monthly Credential Check allowance (UTC calendar month)

sort
string
Default: "name"
Enum: "name" "type" "created_at" "parent_organisation_name" "assets.total" "alerts.total_active" "users.last_login_at"

Field to sort by. Use dot notation for nested properties.

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction (ascending or descending)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/organisations

Creates a customer organisation under a partner and puts it on a tenant plan billed to that partner. The parent must be an MSP partner.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
name
required
string
phone
string
parent_organisation_id
string
plan_slug
required
string

Tenant plan, billed to the partner (GET /organisations/tenant-plans)

extra_assets
integer >= 0

Domains on top of the plan's, each billed at the plan's flat extra-domain price

customer_protection_slug
string or null

Customer Protection band (a tenant-plans entry with add_on customer_protection), billed to the partner on top of the plan

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "phone": "string",
  • "parent_organisation_id": "string",
  • "plan_slug": "string",
  • "extra_assets": 0,
  • "customer_protection_slug": "string"
}

/organisations/{id}

/organisations/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string

Organisation public_id

Responses

Response samples

Content type
application/json
{ }

/organisations/{id}

/organisations/{id}

Authorizations:
apiAuthentication
path Parameters
id
required
string

Organisation ID

Request Body schema: application/json
required
name
string
domain
string
email
string
phone
string
address
string
parentOrganisationId
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "domain": "string",
  • "email": "string",
  • "phone": "string",
  • "address": "string",
  • "parentOrganisationId": "string"
}

/organisations/tenant-plans

Each plan carries the partner's price (list price less its partner discount). Use a plan's slug as plan_slug when creating a tenant or changing its plan. Customer Protection bands (customer-account monitoring) follow the plans with add_on set to customer_protection; use one's slug as customer_protection_slug.

Authorizations:
apiAuthentication
query Parameters
parent_organisation_id
string <uuid>

The partner whose plans to list (defaults to the caller's organisation)

Responses

/organisations/{id}/plan

Puts a tenant on another plan from GET /organisations/tenant-plans, billed to its partner and prorated by day.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Tenant organisation ID

Request Body schema: application/json
required
plan_slug
required
string
extra_assets
integer >= 0

Domains on top of the plan's (omitted keeps the current count)

customer_protection_slug
string or null

Customer Protection band from GET /organisations/tenant-plans (null removes it, omitted keeps the current band)

Responses

Request samples

Content type
application/json
{
  • "plan_slug": "string",
  • "extra_assets": 0,
  • "customer_protection_slug": "string"
}

/organisations/stats

/organisations/stats

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "organisations": {
    },
  • "assets": {
    },
  • "users": {
    },
  • "alerts": {
    }
}

/organisations/alerts

/organisations/alerts

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page (applies to organisations, not individual alerts)

status
string
Enum: "ACTIVE" "UNDER_INVESTIGATION" "CLOSED"

Filter by alert status

from_date
string <date-time>

Filter alerts from this date (ISO 8601)

to_date
string <date-time>

Filter alerts to this date (ISO 8601)

Responses

/organisations/alerts/stats

/organisations/alerts/stats

Authorizations:
apiAuthentication

Responses

/organisations/assets

/organisations/assets

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

keyword
string

Filter assets by hostname keyword

status
string
Enum: "VERIFIED" "UNVERIFIED" "ERROR"

Filter assets by verification status

organisation
string

Filter assets by organisation public_id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

SIEM Export

CEF and LEEF event export for SIEM integration with IBM QRadar, ArcSight, Microsoft Sentinel, and others

/siem/events

Returns credential exposure events as newline-delimited CEF or LEEF formatted events for ingestion by SIEM platforms.

Supported SIEMs:

  • CEF format: ArcSight, Microsoft Sentinel, QRadar, Splunk, and others
  • LEEF format: IBM QRadar (native format, no DSM configuration required)

Format auto-detection: When the format parameter is omitted, QRadar User-Agent strings default to LEEF, all others default to CEF.

This feed carries infostealer findings. Breach findings are exported per alert by /siem/events/{alertId}.

MITRE ATT&CK®: Each event carries the ATT&CK techniques the finding evidences, derived when the event is read. Values are comma-separated IDs; a key is left out when it would be empty.

Meaning CEF LEEF
Technique IDs, e.g. T1555.003,T1589.001 cs6, cs6Label=MitreTechniques mitreTechniques
Tactic IDs in matrix order, e.g. TA0043,TA0006 flexString1, flexString1Label=MitreTactics mitreTactics
Infostealer family as ATT&CK Software ID, e.g. S1240 flexString2, flexString2Label=MalwareFamily malwareFamily

Finding class. The CEF Device Event Class ID is credential-exposure:<class>: stealer-fresh (VERIFIED_FRESH), stealer-reuse (PASSWORD_REUSE_CONFIRMED), combolist (POSSIBLE_COMBOLIST), breach (breach finding) or stealer (provenance not yet known, or INSUFFICIENT_DATA). LEEF events use the event ID CredentialExposure.

Other fields. CEF: suser (identifier), cs1 ServiceURL ([redacted] for an OUTBOUND service that is not one of your monitored assets), cat source (MALWARE or BREACH), cs2 Flow (INBOUND or OUTBOUND), cs3 CredentialType, cn1 ThreatScore (1-5), rt, externalId (finding ID), cs4 AlertID (per-alert export), dhost (monitored asset), cs5 PasswordStrength. LEEF: cat=credential-exposure, sev, sourceType (MALWARE or BREACH), usrName, url, devTime with devTimeFormat, flowDirection, externalId, credentialType, threatScore, alertId, assetHostname, passwordStrength. Severity (0-10) is the threat score doubled, or 5 when unknown.

Incremental sync. Events come back oldest first. Store the X-Next-Cursor response header and pass it as cursor on the next request; repeat while X-Has-More is true, then poll on your normal schedule. Every event is delivered exactly once, however many arrive between polls. Omit cursor on the first request to start from the beginning, or add since to start from a date. The newest minute of events is held back until it settles.

Authorizations:
apiAuthentication
query Parameters
format
string
Enum: "cef" "leef"

Output format. Auto-detected from User-Agent when omitted. QRadar clients default to LEEF, others default to CEF.

since
string <date-time>

ISO 8601 start date. Only events from this time are returned; use it on the first request, then follow the cursor.

hash_emails
boolean
Default: false

Hash email addresses with SHA-256 for privacy

confidence_threshold
integer [ 0 .. 100 ]
Default: 0

Minimum confidence score for events

cursor
string <= 128 characters

Opaque cursor: the X-Next-Cursor header from the previous response. Omit to start from the beginning (or from since).

limit
integer [ 1 .. 500 ]
Default: 100

Events per response (max 500)

Responses

Response samples

Content type
text/plain
Example
CEF:0|DarkStrata|DarkStrata|1.0|credential-exposure:stealer-fresh|Compromised credential: j.smith@example.com on [redacted]|8|suser=j.smith@example.com cs1=[redacted] cs1Label=ServiceURL cat=MALWARE cs2=OUTBOUND cs2Label=Flow cs3=EP cs3Label=CredentialType cn1=4 cn1Label=ThreatScore rt=Oct 18 2026 02:14:00 UTC externalId=3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34 dhost=example.com cs5=weak cs5Label=PasswordStrength cs6=T1555.003,T1589.001,T1539 cs6Label=MitreTechniques flexString1=TA0043,TA0006 flexString1Label=MitreTactics flexString2=S1240 flexString2Label=MalwareFamily

/siem/events/{alertId}

Returns credential exposure events for a single alert as newline-delimited CEF or LEEF formatted events. Infostealer and breach findings are both included: breach findings carry cat=BREACH (CEF, Device Event Class ID credential-exposure:breach) or sourceType=BREACH (LEEF). Every event carries the alert ID (CEF cs4, cs4Label=AlertID; LEEF alertId) and the same MITRE ATT&CK® and other fields as /siem/events.

Authorizations:
apiAuthentication
path Parameters
alertId
required
string <uuid>

Alert public ID

query Parameters
format
string
Enum: "cef" "leef"

Output format. Auto-detected from User-Agent when omitted.

hash_emails
boolean
Default: false

Hash email addresses for privacy

confidence_threshold
integer [ 0 .. 100 ]
Default: 0

Minimum confidence score

Responses

Response samples

Content type
text/plain
Example
CEF:0|DarkStrata|DarkStrata|1.0|credential-exposure:stealer-fresh|Compromised credential: j.smith@example.com on [redacted]|8|suser=j.smith@example.com cs1=[redacted] cs1Label=ServiceURL cat=MALWARE cs2=OUTBOUND cs2Label=Flow cs3=EP cs3Label=CredentialType cn1=4 cn1Label=ThreatScore rt=Oct 18 2026 02:14:00 UTC externalId=3f2b7c1d-9a4e-4b6f-8d21-5c0e7a9b1f34 cs4=550e8400-e29b-41d4-a716-446655440000 cs4Label=AlertID dhost=example.com cs5=weak cs5Label=PasswordStrength cs6=T1555.003,T1589.001,T1539 cs6Label=MitreTechniques flexString1=TA0043,TA0006 flexString1Label=MitreTactics flexString2=S1240 flexString2Label=MalwareFamily
CEF:0|DarkStrata|DarkStrata|1.0|credential-exposure:breach|Compromised credential: a.jones@example.com on linkedin.com|6|suser=a.jones@example.com cs1=linkedin.com cs1Label=ServiceURL cat=BREACH cs2=OUTBOUND cs2Label=Flow cs3=EP cs3Label=CredentialType cn1=3 cn1Label=ThreatScore rt=Oct 18 2026 09:30:12 UTC externalId=8c4d2e6f-1b3a-4c5d-9e7f-0a1b2c3d4e5f cs4=550e8400-e29b-41d4-a716-446655440000 cs4Label=AlertID dhost=example.com cs6=T1589.001 cs6Label=MitreTechniques flexString1=TA0043 flexString1Label=MitreTactics

STIX Export

STIX 2.1 threat intelligence export for alerts and indicators, with Splunk ES and IBM QRadar compatibility

/stix/alerts

Returns credential exposure alerts as STIX 2.1 bundles suitable for SIEM integration. Each alert is converted to a STIX Report containing Indicators and Identities representing the compromised credentials and related threat intel. Infostealer and breach findings both export (source: BREACH in the extension, label source:breach).

STIX Object Types Returned (in this order):

  • report - The alert container with summary metadata (objects[0]; left out when no finding exports)
  • extension-definition - DarkStrata custom extension schema (objects[1])
  • indicator - Individual compromised credentials (or observed-data plus its user-account and domain-name objects in Splunk mode)
  • identity - Compromised user identities (optional, include=identities)
  • relationship - Links between indicators and identities

MITRE ATT&CK®. ATT&CK tags are derived for each finding when the bundle is built:

  • Indicators carry kill_chain_phases (kill_chain_name: mitre-attack, phase_name the tactic shortname, e.g. credential-access) for the techniques' tactics, and one external_references entry per technique (source_name: mitre-attack, external_id e.g. T1555.003, url on attack.mitre.org).
  • The x_darkstrata_credential extension (version 1.1.0, schema at https://api.darkstrata.io/v1/stix/extensions/credential-exposure/v1) carries mitre (techniques with basis observed or inferred, and the infostealer family's ATT&CK Software ID) and provenance (VERIFIED_FRESH, PASSWORD_REUSE_CONFIRMED, POSSIBLE_COMBOLIST or INSUFFICIENT_DATA; infostealer findings only).
  • Splunk-format observed-data carries the indicator's labels (source:*, flow:*, severity-*) plus one mitre:<technique id> label per technique, e.g. mitre:T1555.003.

Splunk Compatibility: Set format=splunk to receive Splunk ES compatible observed-data objects instead of indicator patterns. Splunk ES only parses observed-data, not indicator patterns.

Incremental Sync: Use the since parameter for incremental fetches. Store the last sync timestamp and pass it to retrieve only new/modified alerts since that time.

Authorizations:
apiAuthentication
query Parameters
since
string <date-time>
Example: since=2025-01-01T00:00:00Z

ISO 8601 timestamp for incremental fetch

detail
string
Default: "full"
Enum: "summary" "full"

Level of detail in STIX output

include
string
Example: include=identities

Comma-separated includes (identities)

format
string
Default: "stix21"
Enum: "stix21" "splunk"

Output format. Auto-detected from User-Agent header when Splunk is detected. Explicit value takes precedence over auto-detection.

hash_emails
boolean
Default: false

Hash email addresses for privacy. Identities and Splunk observed-data use sha256: plus the first 16 hex characters of the SHA-256 of the lower-cased address; indicator names and patterns use a shorter hashed_<hex> value.

confidence_threshold
integer [ 0 .. 100 ]
Default: 0

Minimum confidence score for indicators

page
integer >= 1
Default: 1

Page number

limit
integer [ 1 .. 100 ]
Default: 10

Alerts per page (max 100)

Responses

Response samples

Content type
application/stix+json
[
  • {
    }
]

/stix/alerts/{id}

Returns a single credential exposure alert as a complete STIX 2.1 bundle. Useful for fetching detailed threat intelligence for a specific alert.

The bundle includes the alert as a STIX Report (objects[0]), the extension definition (objects[1]) and all associated indicators, identities, and relationships. Infostealer and breach findings both export.

Indicators carry MITRE ATT&CK® kill_chain_phases, external_references and the extension's mitre and provenance; Splunk-format observed-data carries mitre:<technique id> and severity-* labels. See GET /stix/alerts for details.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Alert public ID

query Parameters
detail
string
Default: "full"
Enum: "summary" "full"

Level of detail in STIX output

include
string

Comma-separated includes (identities)

format
string
Default: "stix21"
Enum: "stix21" "splunk"

Output format. Auto-detected from User-Agent header when Splunk is detected. Explicit value takes precedence over auto-detection.

hash_emails
boolean
Default: false

Hash email addresses for privacy

confidence_threshold
integer [ 0 .. 100 ]
Default: 0

Minimum confidence score

Responses

Response samples

Content type
application/stix+json
Example
{
  • "type": "bundle",
  • "id": "bundle--f9b2fd53-4335-4b51-a84c-0e1f2a3b4c5d",
  • "objects": [
    ]
}

/stix/indicators

Returns infostealer credential findings as STIX Indicators (or observed-data in Splunk mode). This endpoint provides a flat list of all indicators without the alert grouping, useful for bulk import into threat intelligence platforms. The bundle starts with the extension definition. Breach findings are exported per alert by /stix/alerts.

Incremental sync. Pass cursor (empty on the first request) to page by cursor instead of by page number: indicators come back oldest first, store the X-Next-Cursor response header and pass it back as cursor, repeating while X-Has-More is true. Every indicator is delivered exactly once. since still sets the start date and page is ignored. The newest minute is held back until it settles. Without cursor the endpoint keeps its page-number behaviour (newest first).

DarkStrata Extension: Each indicator includes the extension-definition--d6132570-7659-4922-9fc4-420e4f8cba63 extension with additional metadata:

  • source: MALWARE or BREACH
  • flow: INBOUND or OUTBOUND
  • service_url: The service where credentials were exposed
  • threat_score: Severity level (1-5)
  • password_strength: weak/medium/strong
  • credential_type: EP (email/password) or UP (username/password)
  • provenance: infostealer provenance label (VERIFIED_FRESH, PASSWORD_REUSE_CONFIRMED, POSSIBLE_COMBOLIST, INSUFFICIENT_DATA)
  • mitre: MITRE ATT&CK® techniques (each observed or inferred) and the infostealer family's ATT&CK Software ID

MITRE ATT&CK®. ATT&CK tags are derived for each finding when the bundle is built:

  • Indicators carry kill_chain_phases (kill_chain_name: mitre-attack, phase_name the tactic shortname, e.g. credential-access) for the techniques' tactics, and one external_references entry per technique (source_name: mitre-attack, external_id e.g. T1555.003, url on attack.mitre.org).
  • The x_darkstrata_credential extension (version 1.1.0, schema at https://api.darkstrata.io/v1/stix/extensions/credential-exposure/v1) carries mitre (techniques with basis observed or inferred, and the infostealer family's ATT&CK Software ID) and provenance (VERIFIED_FRESH, PASSWORD_REUSE_CONFIRMED, POSSIBLE_COMBOLIST or INSUFFICIENT_DATA; infostealer findings only).
  • Splunk-format observed-data carries the indicator's labels (source:*, flow:*, severity-*) plus one mitre:<technique id> label per technique, e.g. mitre:T1555.003.

Confidence Mapping: DarkStrata threat scores are mapped to STIX confidence:

  • Level 1 (Info) → Confidence 20
  • Level 2 (Low) → Confidence 40
  • Level 3 (Medium) → Confidence 60
  • Level 4 (High) → Confidence 80
  • Level 5 (Critical) → Confidence 100
Authorizations:
apiAuthentication
query Parameters
since
string <date-time>

ISO 8601 timestamp for incremental fetch

format
string
Default: "stix21"
Enum: "stix21" "splunk"

Output format. Auto-detected from User-Agent header when Splunk is detected. Explicit value takes precedence over auto-detection.

hash_emails
boolean
Default: false

Hash email addresses for privacy. Splunk observed-data uses sha256: plus the first 16 hex characters of the SHA-256 of the lower-cased address; indicator names and patterns use a shorter hashed_<hex> value.

confidence_threshold
integer [ 0 .. 100 ]
Default: 0

Minimum confidence score to include

page
integer >= 1
Default: 1

Page number (ignored when cursor is set)

cursor
string <= 128 characters

Opaque cursor: the X-Next-Cursor header from the previous response. Pass an empty value on the first request to start cursor paging.

limit
integer [ 1 .. 500 ]
Default: 100

Indicators per page (max 500)

Responses

Response samples

Content type
application/stix+json
Example
{
  • "type": "bundle",
  • "id": "bundle--6e5d4c3b-2a19-4f08-b7e6-d5c4b3a29180",
  • "objects": [
    ]
}

Usage

API usage statistics and rate limit monitoring

/api/usage

Returns API usage statistics for the current organisation. Can filter by specific API key, date range, and granularity.

Authorizations:
apiAuthentication
query Parameters
kid
string

Filter by specific API key (kid)

start_date
string <date>

Start date for the query range (YYYY-MM-DD)

end_date
string <date>

End date for the query range (YYYY-MM-DD)

granularity
string
Default: "daily"
Enum: "hourly" "daily"

Data granularity (hourly or daily)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/usage/summary

Returns a summary of API usage for the current billing period. Useful for displaying usage against plan limits.

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
{
  • "api_keys_used": 0,
  • "total_calls": 0,
  • "first_call": "2019-08-24T14:15:22Z",
  • "last_call": "2019-08-24T14:15:22Z",
  • "period_start": "2019-08-24T14:15:22Z"
}

/api/usage/by-key

Returns API usage grouped by API key for the current billing period. Shows which API keys are generating the most traffic.

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Users

User management within organisations

/users

/users

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

search
string

Keyword filter applied to names and identifiers

role
string

Filter by user role

verify_status
string
Enum: "UNVERIFIED" "VERIFIED" "PENDING_REVIEW" "SUSPENDED"

Filter by user verification status. If not provided, all users are returned. Use PENDING_REVIEW to show users awaiting approval, VERIFIED for approved users, UNVERIFIED for new unverified users, or SUSPENDED for suspended accounts.

sort
string
Default: "email"

Field to sort by

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/users/roles

/users/roles

Authorizations:
apiAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/users/invite

/users/invite

Authorizations:
apiAuthentication
Request Body schema: application/json
required
email
required
string <email>

Email address of the user to invite

role_id
required
string

Role ID to assign to the invited user

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "message": "string",
  • "invitation_id": "string"
}

/users/invitations

/users/invitations

Authorizations:
apiAuthentication
query Parameters
page
integer >= 1
Default: 1

Page number

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

status
string
Enum: "pending" "expired" "accepted" "revoked"

Filter by invitation status

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/users/invitations/{id}/resend

/users/invitations/{id}/resend

Authorizations:
apiAuthentication
path Parameters
id
required
string

Invitation ID

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

/users/invitations/{id}/revoke

/users/invitations/{id}/revoke

Authorizations:
apiAuthentication
path Parameters
id
required
string

Invitation ID

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

/users/{id}/suspend

Suspends a user account, preventing them from logging in. Suspended users cannot re-register.

Authorizations:
apiAuthentication
path Parameters
id
required
string

User ID

Request Body schema: application/json
optional
reason
string

Reason for suspension

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

/users/{id}/unsuspend

Restores a suspended user account to VERIFIED status, allowing them to log in again.

Authorizations:
apiAuthentication
path Parameters
id
required
string

User ID

Responses

Webhooks

Webhook configuration and management

/webhooks/events

Returns the catalogue of event keys (e.g. alert.stealer_log.created) that webhooks can subscribe to. Alert events carry MITRE ATT&CK® tags in data.alert.mitre; the delivery body is described under PUT /webhooks (WebhookAlertDelivery).

Authorizations:
apiAuthentication
query Parameters
page
string

Page number (default 1)

limit
string

Results per page (default 50)

namespace
string

Filter by event namespace (e.g. ALERT, ASSET, API_KEY)

keyword
string

Filter by event key, title, or description

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/webhooks

Returns the organisation's webhooks with status and last delivery result.

Authorizations:
apiAuthentication
query Parameters
page
string

Page number (default 1)

limit
string

Results per page (default 10)

keyword
string

Filter by name or description

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/webhooks

Registers a webhook that receives subscribed events by HTTP push. Event keys come from GET /webhooks/events.

Delivery payload. A GENERIC webhook receives a JSON envelope (event, event_id, occurred_at, data, timestamp, webhook_public_id, organisation). For the alert events alert.stealer_log.created, alert.breach_exposure.created, alert.lens.password_use_confirmed, alert.lens.supplier_password_use_confirmed and vip.alert.created, data.alert.mitre carries the MITRE ATT&CK® techniques and infostealer software the finding evidences, each with a basis of observed or inferred. The full body is the WebhookAlertDelivery schema, shown under this operation's alertDelivery callback. DATTO, CONNECTWISE, AUTOTASK and STIX_2_1 currently receive the same JSON envelope as GENERIC; a Slack incoming-webhook URL receives a Slack message; the ticketing types (SERVICE_NOW, JIRA, ZENDESK, FRESHDESK) open a ticket built from the envelope; a custom payload template replaces the envelope. To verify deliveries, see Webhook signatures.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
url
required
string

Endpoint URL to deliver events to

name
required
string
description
string
events
Array of strings

Event keys to subscribe to

integration_type
string
Enum: "GENERIC" "SLACK" "SERVICE_NOW" "JIRA" "ZENDESK" "FRESHDESK" "DATTO" "CONNECTWISE" "AUTOTASK" "STIX_2_1"
content_type
string
is_enabled
boolean
Default: true
retryCount
integer
Default: 3
timeout
integer
Default: 30000

Delivery timeout in milliseconds

include_child_organisations
boolean
Default: false

Also deliver events from every client organisation below this one (MSP partners only; needs a plan with msp). Each delivery then carries source_organisation (id, name, is_client, depth, path from this organisation down to the source) naming exactly which client the event came from.

Array of objects
object

Responses

Callbacks

Request samples

Content type
application/json
{
  • "url": "string",
  • "name": "string",
  • "description": "string",
  • "events": [
    ],
  • "integration_type": "GENERIC",
  • "content_type": "string",
  • "is_enabled": true,
  • "retryCount": 3,
  • "timeout": 30000,
  • "include_child_organisations": false,
  • "headers": [
    ],
  • "authentication": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Callback payload samples

Callback
POST: Alert event delivery
Content type
application/json
{
  • "event": "alert.stealer_log.created",
  • "event_id": "0b9f6c1e-2d3a-4f5b-8c7d-9e0f1a2b3c4d",
  • "occurred_at": "2026-10-19T06:00:04.112Z",
  • "data": {
    },
  • "timestamp": "2026-10-19T06:00:04.130Z",
  • "webhook_id": 42,
  • "webhook_public_id": "7c1d2e3f-4a5b-4c6d-8e7f-901a2b3c4d5e",
  • "organisation": {
    }
}

/webhooks/test-connection

Validates connection details for a service-desk integration (ServiceNow, Zendesk, Jira, Freshdesk) without creating a webhook.

Authorizations:
apiAuthentication
Request Body schema: application/json
required
integration_type
required
string
Enum: "SERVICE_NOW" "ZENDESK" "JIRA" "FRESHDESK"
required
object

Responses

Request samples

Content type
application/json
{
  • "integration_type": "SERVICE_NOW",
  • "serviceDeskConfig": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "error": "string"
}

/webhooks/{id}

Returns URL, headers, authentication, subscribed events, and delivery settings. Secret values are returned decrypted for editing.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Webhook ID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "name": "string",
  • "description": "string",
  • "events": [
    ],
  • "is_enabled": true,
  • "include_child_organisations": true,
  • "retry_count": 0,
  • "timeout": 0,
  • "integration_type": "string"
}

/webhooks/{id}

Full replace of the webhook's configuration — omitted optional fields reset to defaults (e.g. omitting authentication clears it). Fetch the current config first and send the complete desired state. Body shape matches PUT /webhooks.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Webhook ID

Request Body schema: application/json
required
url
required
string
name
required
string
description
string
events
Array of strings
integration_type
string
is_enabled
boolean
retryCount
integer
timeout
integer
include_child_organisations
boolean

Also deliver events from every client organisation below this one (MSP partners only; needs a plan with msp). Each delivery then carries source_organisation (id, name, is_client, depth, path from this organisation down to the source) naming exactly which client the event came from. Unlike the other fields, omitting it keeps the current value.

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "name": "string",
  • "description": "string",
  • "events": [
    ],
  • "integration_type": "string",
  • "is_enabled": true,
  • "retryCount": 0,
  • "timeout": 0,
  • "include_child_organisations": true
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

/webhooks/{id}

Permanently deletes a webhook and its event subscriptions. This action cannot be undone.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Webhook ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

/webhooks/{id}/deliveries

One entry per delivery (newest first), updated in place as it is retried. Failed and retrying deliveries carry the HTTP status and error. Retries back off from 1 minute to 24 hours; 4xx responses other than 408, 425 and 429 are not retried.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Webhook ID

query Parameters
page
integer >= 1
Default: 1
limit
integer [ 1 .. 100 ]
Default: 20
status
string
Enum: "SUCCESS" "FAILED" "RETRYING" "PENDING"

Only deliveries in this state

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/webhooks/{id}/test

Dispatches a test delivery so you can verify the endpoint receives events.

Authorizations:
apiAuthentication
path Parameters
id
required
string <uuid>

Webhook ID

Request Body schema: application/json
optional
event
string

Event key to simulate (default: webhook.test)

payload
object

Custom test payload

Responses

Request samples

Content type
application/json
{
  • "event": "string",
  • "payload": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "jobId": "string"
}