Skip to main content
Version: 3.0.0

CloudSEK Alerts, Incidents and Events APIs, including the Bi-Directional (Two-Way) Suite

Connect the CloudSEK platform with your SIEM, SOAR, ITSM, messaging and EDR tools in both directions. Poll the latest alerts, lifecycle changes and entity snapshots detected for your organization, and write operational state (status, priority, assignee, comments and remediation) back into CloudSEK so that both systems stay in sync.

These APIs provide:

Read (poll)

  • Alerts: Live incident alerts from Deep & Dark Web Monitoring, Brand Risk Monitoring, Data Leak Monitoring and Infrastructure Monitoring
  • Alerts v2: Enhanced alerts with issue_metadata for BeVigil scanner modules
  • Historic Alerts / Historic Alerts v2: Incident alerts from the last 30 days
  • Changelog: Audit-style change events for incidents, events and comments. Changes made through the two-way write APIs also appear here and carry the operation_id of the write that produced them.
  • Snapshots: Point-in-time state of events and incidents with filtering, useful for reconciliation

Write (two-way, new in the Bi-Directional release)

  • Incidents: Update status and priority, reassign by email, and add comments. Incidents are addressed by their Display ID, for example XVA-1234.
  • Events: Update status, reassign, comment, and remediate with a closure comment. Events are addressed by their event_record_identifier.
  • Bulk: Asynchronous bulk status, priority and assignee operations. Poll GET /v2/jobs/{jobId} for per-record outcomes (cursor-paginated).

Common integration patterns:

  • SIEM ingestion: Poll /v2/incidents/alerts (and the historic alerts endpoints for backfill), then follow lifecycle changes on /v2/changelog using the sortable_id cursor to resume from wherever the last request ended.
  • SOAR playbooks: Acknowledge, comment, assign and close incidents or events directly. Pass an external_reference ({system, ticket_id, url}) on writes so the CloudSEK changelog and UI timeline link back to your ticket.
  • ITSM sync: Mirror ticket transitions into incident status. Writes are idempotent and comments are deduplicated, so retries are safe.
  • Bulk triage: Close, re-prioritise or reassign large sets of incidents or events asynchronously, then audit per-record success or failure through the jobs API.
  • Reconciliation: Verify state with the snapshot endpoints. When consuming the changelog, skip entries whose integrationMetadata and operationId identify your own integration's writes, so you do not echo your own changes back.

Depending on the product you've purchased (XVigil/BeVigil) and the submodules you're subscribed to, the response provides comprehensive event information along with incident details (ID, URL, timestamps, priority, status, etc.) in JSON format.

v2 Enhancements: The v2 alerts endpoints include enriched issue_metadata for BeVigil scanner modules (WebAppScanner, NetworkScanner, DNSScanner, MobileAppScanner, APIScanner, CVEScanner, CloudScanner, SSLScanner) with detailed vulnerability information including CVE/CWE IDs, CVSS scores, remediation guidance, and impact analysis.

Identifiers: Incidents are referenced by their client-facing Display ID, for example XVA-1234. Legacy internal UUIDs are deprecated on changelog lookups and are not accepted on write routes. Events are referenced by their base64 event_record_identifier. The org_id parameter is optional everywhere; tenancy is inferred from the token and the target identifier.

Module names: Filters speak canonical module KEYS, for example CompromisedComputers or FakeMobileApps. The same keys come back in changelog rows, snapshot rows and write responses, so a value read from any of those can go straight into any filter. The alert payload's module_name (category, for example "Brand Risk Monitoring") and sub_module (module, for example "Fake Mobile Apps") are display fields for humans; to derive the canonical key from an alert, remove the spaces from sub_module.

Vocabulary: Incident priority is P0, P1 or P2 everywhere: alert payloads, snapshot rows, filters and write bodies all use the same three values, so priorities round-trip without mapping. Status values use the client-facing labels (Open, Acknowledged, InProgress, ClosedResolved and the other Closed variants). All enum inputs are exact-match and case-sensitive: send P1, not p1, and Open, not open; a wrong-case value is rejected with 400 VALIDATION_ERROR.

Data Retention:

  • Historic Alerts: 30 days from integration setup
  • Changelog: 30 days of activity logs

Authentication: All endpoints require Bearer token authentication via the Authorization header. Create or rotate your token in the CloudSEK platform under Integrations → Alerts API → Create token (or Rotate Token). One token covers both reading and writing: every Alerts API token issued from 30 July 2026 carries write access natively. A token created before that date does not, so if a write route is refused, rotate the token against your existing integration configuration and the replacement will have write access. Nothing else needs to change, and read routes keep working throughout.

Rate Limits: Read APIs are limited to 20 requests per minute per token (across all read endpoints, not per endpoint). Write APIs have separate per-token budgets for single-entity and bulk operations; see the Bi-Directional section below. 429 responses include a Retry-After header.

Bi-Directional (Two-Way) Write APIs​

A controlled, audited write surface that lets external SIEM, SOAR and ITSM systems push operational state back into CloudSEK: incident status, priority, assignee and comments; event status, assignee, comments and remediation; and asynchronous bulk operations with job polling. Every accepted write is attributed to a resolved actor, recorded in an inbound audit log, and surfaced through the changelog. Authentication and identifier conventions are described in the introduction above.

Response envelope. Every write returns:

{
  "success": true,
  "data": { "incident_display_id": "XVA-224", "changed": true },
  "operation_id": "0194a3b2-c7d1-78e2-a3f4-5b6c7d8e9f01",
  "request_id": "req-20260511-abc123",
  "timestamp": "2026-05-18T10:30:00.000Z"
}

The top-level operation_id (a UUID v7) is the correlation identifier for the write. Every changelog entry produced by an accepted write carries it, so GET /v2/changelog?operation_id=... returns exactly what your integration changed. This also lets you avoid echoing your own changes back into CloudSEK.

Idempotency and dedup. Re-submitting an identical single write against an unchanged record returns a no-op success whose data is a slim payload: a message ("No changes required - current state already matches") plus reconciled_from_request_id, the request_id of the write that last changed the record. Posting a comment with identical text to the same record from the same integration returns the prior write's operation_id instead of creating a duplicate. Identical remediations replay the prior operation_id. Remediation always writes its closure comment, though, so a call that repeats the status but changes the comment text is not a no-op: the status stays put and a new comment is created.

Bulk jobs. Both bulk routes return 202 with the same accept shape: \{job_id, state, accepted, status_url\}. Job states are queued, running, and the terminal completed or failed; poll GET /v2/jobs/{jobId} until the state is terminal. A job-level failed state means the job could not run to completion; record-level problems inside a job that completes surface as outcome: failed records instead, so check both levels. The response carries a summary (total, success, skipped, failed) that reconciles with the per-record records array, cursor-based pagination over records (cursor parameter, page_info.next_cursor), and an outcome filter (success, skipped, failed) for triaging large jobs. A skipped record means the entity was already in the target state (reason already_in_target_status); a failed record carries a reason such as not_found.

Write rate limits. Applied per token, separately from the read limit above. Single-entity writes and bulk submissions have their own budgets. On 429 RATE_LIMIT_EXCEEDED, honour the Retry-After header.

Write error codes.

HTTPCodes
400VALIDATION_ERROR, INVALID_STATUS_TRANSITION, COMMENT_REQUIRED, INVALID_DISPLAY_ID, USER_NOT_FOUND, BULK_ACTION_FIELD_MISMATCH, BULK_LIMIT_EXCEEDED
401UNAUTHORIZED
403ACCESS_DENIED, TWO_WAY_DISABLED, MODULE_ACCESS_DENIED, INCIDENT_ARCHIVED, ASSIGNEE_MODULE_ACCESS_DENIED, USER_INACTIVE, ORG_INACTIVE, ORG_EXPIRED, INTEGRATION_CONFIG_INACTIVE
404INCIDENT_NOT_FOUND, EVENT_NOT_FOUND, JOB_NOT_FOUND
409CONFLICT
429RATE_LIMIT_EXCEEDED (includes Retry-After)
5xxINTERNAL_ERROR, INTEGRATION_AUTH_UNAVAILABLE, INTEGRATION_PLATFORM_UNAVAILABLE, INTEGRATION_REQUEST_TIMEOUT

Authentication​

Bearer token created under Integrations → Alerts API in the CloudSEK platform. Tokens issued from 30 July 2026 carry both read and write access; a token issued earlier is read-only on the write routes until it is rotated.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT