Skip to content

Sending Alerts

Raises a security or availability alert as an Alert ticket on a named system. Use it from a SIEM, a cloud security service, a monitoring platform, or any detection pipeline that should put a finding in front of a responder.

Alerts land unassigned and are picked up by the platform's own routing. Escalating an alert to an Incident is a separate, deliberate step taken in the platform; this endpoint never changes a ticket's type.

Before you start: you need a token. See Authentication.

Minimal call

Only the system and a summary are required.

{
  "site_id": 18,
  "summary": "Root login from unrecognised ASN"
}

Fields

Field Required Default Notes
site_id / system_name one of - See Identifying the system
summary yes - The alert title. Becomes the ticket summary
details no summary Body text. HTML accepted
category no Alerts and Incidents Must come from the list below - validated, not trusted
external_id no generated Your identifier for the alert. This is the dedup key
priority no 3 1 Critical, 2 High, 3 Medium, 4 Low
status_id no 1 (New) Any valid status id
detection_source no - What detected it, e.g. AWS GuardDuty
internal_indicators no - Internal indicators of compromise
external_indicators no - External indicators of compromise
mitre_tactics no - Comma-separated, from the list below
mitre_techniques no - Free text, e.g. T1078, T1110
mitre_subtechniques no - Free text, e.g. T1078.004
related_cves no - Free text, e.g. CVE-2026-1234
root_cause no - Usually filled later, during after-action review
lessons_learned no - Usually filled later
corrective_actions no - Usually filled later

Compliance attribution (the FedRAMP and CMMC control and requirement fields) is derived automatically from the category. Do not send it.

Send an external_id

external_id is your own identifier for the alert, and it is what makes repeat calls safe.

  • Send one, and re-posting updates the existing ticket. Retries do not duplicate, and you can enrich an alert with a second call.
  • Omit it and every call raises a new ticket. A monitoring system that retries on timeout will flood the queue.

The dedup key is the system plus your external_id, so the same identifier on two different systems correctly produces two tickets.

Enriching an alert later

Post a thin alert the moment you detect something, then fill in what you learn:

{
  "site_id": 18,
  "external_id": "guardduty-a41f9c02",
  "summary": "Root login from unrecognised ASN",
  "root_cause": "Long-lived access key committed to a public repository.",
  "corrective_actions": "Key revoked, repository history purged, detection rule added."
}

summary is required on every call, enrichment included, so re-send the alert title. Every other field you omit keeps its current value, including the ones you set on the first call. An enrichment post will not reset the alert's priority, status, category or details.

Allowed values

category

Anything outside this list is rejected. Use > as the separator with no spaces around it, and send the path, never a numeric id.

Alerts and Incidents
Alerts and Incidents>Availability
Alerts and Incidents>Availability>Automation Error
Alerts and Incidents>Availability>Backup Failure
Alerts and Incidents>Availability>KSI
Alerts and Incidents>Availability>Resource Exhaustion
Alerts and Incidents>Availability>Security Functionality
Alerts and Incidents>Availability>System Error
Alerts and Incidents>Availability>System Outage
Alerts and Incidents>Performance
Alerts and Incidents>Performance>Disk Full
Alerts and Incidents>Performance>High Resource Usage
Alerts and Incidents>Performance>Network Latency
Alerts and Incidents>Security
Alerts and Incidents>Security>Audit Log Failure
Alerts and Incidents>Security>Data Exfiltration
Alerts and Incidents>Security>Denial of Service
Alerts and Incidents>Security>Integrity Violation
Alerts and Incidents>Security>Malware
Alerts and Incidents>Security>Phishing
Alerts and Incidents>Security>Policy Violation
Alerts and Incidents>Security>Suspicious Activity
Alerts and Incidents>Security>Unauthorized Access
Alerts and Incidents>Security>Unauthorized Change
Alerts and Incidents>Security>Unauthorized Software

The category drives compliance attribution, so choosing the most specific path that fits gets you better control mapping than defaulting to the top level.

The endpoint validates against your tenant's live category tree, not against this printed list. If your tenant's categories have been customised, the tree is authoritative and this list is a guide.

mitre_tactics

Comma-separated. Use values from this list:

Reconnaissance | Resource Development | Initial Access | Execution | Persistence |
Privilege Escalation | Defense Evasion | Credential Access | Discovery |
Lateral Movement | Collection | Command & Control | Exfiltration | Impact

Example: "mitre_tactics": "Initial Access, Persistence"

Values outside this list are not validated by the endpoint.

MITRE tactics are not currently recording

Tactics sent to this endpoint are accepted but do not persist to the ticket. This is a platform-level limitation with multi-select fields rather than a payload problem, and it is being tracked. Send the values, since they will start recording once it is resolved, but do not rely on them being present until then. The other MITRE fields, mitre_techniques and mitre_subtechniques, are free text and record normally.

priority

1 Critical, 2 High, 3 Medium, 4 Low. These are the Incident SLA's tiers, so response and resolution targets follow from your choice. A value outside 1-4 falls back to the ticket's current priority, or to 3 on a new alert.

Rejections

Code Rejected because
51101 summary missing
51102 Neither site_id nor system_name sent
51103 No system matched
51104 category is not in the allowed list
51105 The create step returned no usable ticket id

Full example

{
  "site_id": 18,
  "summary": "Root login from unrecognised ASN",
  "details": "Console sign-in for the management account from 203.0.113.44 (AS64512), no prior history.",
  "category": "Alerts and Incidents>Security>Unauthorized Access",
  "external_id": "guardduty-a41f9c02",
  "priority": 2,
  "detection_source": "AWS GuardDuty",
  "external_indicators": "203.0.113.44",
  "mitre_tactics": "Initial Access, Privilege Escalation",
  "mitre_techniques": "T1078.004"
}