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 credential for the endpoint's authentication method, a bearer token by default. 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 on create existing title The alert title. Becomes the ticket summary. Omit it on a re-post and the current title is kept
details no summary Body text. HTML accepted
note no - Appends a note to the ticket as an analyst action. Additive - every call carrying a note adds one; see Adding a note. 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",
  "root_cause": "Long-lived access key committed to a public repository.",
  "corrective_actions": "Key revoked, repository history purged, detection rule added."
}

summary is omitted here, so the alert keeps the title it was raised with. summary is required only when the alert is first created. Every field you omit on an enrichment post keeps its current value, including the ones you set on the first call, so the post will not reset the alert's summary, priority, status, category or details.

Adding a note

Send a note and the platform appends it to the ticket as an analyst action, the same kind of note a responder adds by hand. Use it to attach triage context to an alert as it lands, or to record what a later enrichment call found.

Notes are additive: every call that carries a note adds one, with no de-duplication. This lets an alert accumulate a running log, but it also means a note belongs on a call you make once, not on a payload your retry logic re-sends. If your caller retries on timeout with the note still in the body, the same note lands twice.

{
  "site_id": 18,
  "external_id": "guardduty-a41f9c02",
  "note": "Confirmed with the account owner: the sign-in was an authorised break-glass action. Downgrading."
}

The platform renders note as HTML, so it reads a < in plain text as markup. Send HTML deliberately, or escape angle brackets in text you did not intend as markup.

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"

Send the tactic names exactly as listed. A value that is not one of the fourteen is ignored, and any valid ones in the same call still record, so one unrecognised name will not drop the rest.

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 on a new alert (a re-post inherits the existing title)
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
51106 A note was supplied but no ticket id was available

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"
}